Annex C

Introduction

ECSS-E-TM-10-25A Annex C specifies the implementation technology that is required to exchange data that complies with the data model specified in ECSS-E-TM-10-25A Annex A. Annex C prescribes 2 technologies that need to be supported by an implementation for it to be fully compliant with ECSS-E-TM-10-25A:

• JSON REST API
• JSON Exchange File Format

The CDP4 is fully compliant with the standard. The CDP4-SDK can be used to create applications client and server side that implement the JSON REST API. It also provides an implementation of to read from and write a file that conforms to the JSON Exchange File Format. The CDP4 Desktop application can communicate with a JSON REST API, of which the CDP4 Web Services are an implementation. The CDP4 Web Services can export data to a JSON Exchange File Format and can be seeded from a JSON Exchange File Format.

JSON REST API

The JSON REST API is a particular flavor of REST. Two HTTP verbs are supported: GET and POST, DELETE, PUT and PATCH are not supported. GET requests are used to retrieve data. POST requests are used to create, update and delete data; multiple operations are supported in one POST request, allowing an API user to add, update and delete different objects with one request.

GET requests

In order to retrieve data from a server a GET request must be performed. A GET request is performed along the containment hierarchy specified by Annex A. Annex A provides two so-called TopContainer classes, the SiteDirectory and EngineeringModel. The GET requests can only be performed on either the SiteDirectory and EngineeringModel URI's. The subsequent parts of the URI follow the aggregate composition properties of Annex A. To GET a specific Thing the unique identifier, represented by the {iid} token, needs to be specified as well. The {iid} token must be a valid UUID version 4.

nr.	Method	Request	Notes
[1]	GET the singleton SiteDirectory object	http[s]://cdp4services-public.rheagroup.com/SiteDirectory[/*]	Specifying * is not mandatory but allowed and will return the same result
[2]	GET the singleton SiteDirectory object specified by its unique identifier	http[s]://cdp4services-public.rheagroup.com/SiteDirectory/{iid}	The unique identifier can be retrieved using [1]
[3]	Get the email address of a person contained in the SiteDirectory	http[s]://cdp4services-public.rheagroup.com/SiteDirectory/{iid}/person/{iid}/email/{iid}	Note that person and email are all lower-case
[4]	Get all the email addresses of a person contained in the SiteDirectory	http[s]://cdp4services-public.rheagroup.com/SiteDirectory/{iid}/person/{iid}/email[/*]	the /* is not mandatory but allowed and will return the same result as when not provided
[5]	GET an EngineeringModel specified by its unique identifier	http[s]://cdp4services-public.rheagroup.com/EngineeringModel/{iid}	-
[6]	GET the Iteration object, specified by its unique identifier, that is contained by the specified EngineeringModel	http[s]://cdp4services-public.rheagroup.com/EngineeringModel/{iid}/iteration/{iid}	Note that iteration is a property of the EngineeringModel and that it is provided with lower-case.

The result of a GET request is JSON array of JSON objects that represent ECSS-E-TM-10-25 Annex A objects. The ClassKind property of the Thing class denotes its type and is used for serialization and deserialization purposes.

Annex C also supports query parameters. These query parameters are used to either narrow or widen the scope of the expected result. The following query parameters are supported and may be used in combination, unless specified otherwise:

parameter	value	description	Combination
revisionNumber	an integer value greater than or equal to zero	Returns the set of all objects contained by the object specified in the URI, that have a revisionNumber that is greater than the given value. This enables getting the net change of objects since a previous revision. Note: Specifying revisionNumber=0 is equivalent to specifying extent=deep.	revisionNumber=n may only be used as a single query parameter, no combination with other query parameters shall be allowed nor supported.
extent	shallow (default value) or deep	when deep is specified the requested object including all the objects contained by it along the complete containment tree	includeReferenceData, includeAllContainers, includeFileData
includeReferenceData	false (default value) or true	For a request on a SiteDirectory return all contained reference data objects. For a request on an EngineeringModel return all reference data objects from the chain of required ReferenceDataLibrary objects referenced by that EngineeringModel, as defined through the requiredRdl properties.	extent, includeAllContainers, includeFileData
includeAllContainers	false (default value) or true	In addition to the requested object, return all containers in the containing composite structure from the lowest level specified in the URI up to the top container.	extent, includeReferenceData, includeFileData
includeFileData	false (default value) or true	In addition to the requested object(s), return all data associated with FileRevision objects (i.e. file content) in the (multi-part) reply.	extent, includeReferenceData, includeAllContainers

NOTE: Even though the includeReferencaData query parameter is provided it is not recommended to use this when performing a GET request on an Iteration in an EngineeringModel. From the URI of the GET request it is possible to determine what Iteration instance the response is related to. This is useful when determining the containment tree in client applications of said data since the unique identifiers of objects contained in Iterations is not truly unique across the Iterations in an EngineeringModel. When Reference Data is returned as well it may become difficult to determine to what containment tree this data belongs, not so much for the reference data itself, but for concepts such as Alias, Definition and Hyperlink, these classes may be contained by data in the EngineeringModel containment tree and SiteDirectory Tree.

More information coming soon

POST requests

More information coming soon

Side Effects

More information coming soon

JSON Exchange File Format

The JSON Exchange File Format is used to exhange a Site Directory, Reference Data Libraries and Engineering Models between 2 parties. The CDP4 Web Services can be initialized, or seeded, from such a file. The archive is an implementation neutral means to exchange ECSS-E-TM-10-25 data.

ECSS-E-TM-10-25 does not specify how Annex C.2 implentations should store the data, this is an implementation detail. The CDP4 Web Services make use of a relational database called PostgreSQL. Other impementations may use a different kind of database, or different SQL schema.

The exchange file is a ZIP archive that contains multiple folders and files. These files contain ECSS-E-TM-10-25 objects that are serialized as a JSON array of JSON objects; the serialization is similar to serialization used in the response of a GET request as specified in Annex C.2. The following folders and files are contained in the ZIP archive:

• One Header File named Header.json, in the root folder;
• One SiteDirectory File named SiteDirectory.json, in the root folder;
• A SiteReferenceDataLibraries folder that contains zero or more SiteReferenceDataLibrary File;
• A ModelReferenceDataLibraries folder that contains zero or more ModelReferenceDataLibrary File;
• An EngineeringModels folder containing zero or more EngineeringModel Folder, where each EngineeringModel Folder contains:
  • One EngineeringModel File;
  • One Iterations folder that contains one or more Iteration File;
  • One FileRevisions folder that contains zero or more FileRevision File;
• Zero or one Extensions folder that may contain any application-dependent folders and files.

Header File

• The archive contains one Header File which is named "Header.json".
• The Header File is stored in the root folder of the archive.
• The Header File contains the following information, in the form of a single JSON object with the following string or null valued properties:
  • mediaType: fixed identifier of the media type, which shall be application/ecss-e-tm-10-25+json.
  • dataModelVersion: version identifier of the ECSS-E-TM-10-25 Annex A Data Model that was used to produce the file.
  • exchangeFileFormatVersion: version identifier of the ECSS-E-TM-10-25 Annex C JSON Exchange File Format (i.e. this specification) that was used to produce the file.
  • creatorOrganization: a JSON object representing the organization that created the archive, with the following properties name, organizationalUnit, locality, iid.
    • name: the common name of the creator organization.
    • organizationalUnit: the name or abbreviation of a unit inside the creator organization (optional).
    • locality: a description of the geographic location of the creator organization (optional).
    • iid: a UUID v4 serialised string that should match the iid of the corresponding Organization object inside the SiteDirectory File (optional).
  • copyright: textual copyright information (optional).
  • creatorPerson: identification of the person responsible for the archive.
    • givenName: given name of the person (optional).
    • surname: surname of the person.
    • email: e-mail address of the person responsible for the archive (optional).
    • iid: a UUID v4 serialised string that should match the iid of the corresponding Person object inside the SiteDirectory File (optional).
  • createdOn: created-on timestamp.
    • utc: a timestamp in ISO 8601 UTC format.
    • local: a timestamp in ISO 8601 local timezone format (optional).
  • lastModifiedOn: last-modified timestamp in ISO 8601 UTC format (optional).
    • utc: a timestamp in ISO 8601 UTC format.
    • local: a timestamp in ISO 8601 local timezone format (optional).
  • remark: free format textual remark (optional).
  • extensions: freely usable JSON object to capture any extensions used by an implementation (optional). It can be used to describe corresponding content in the Extensions Folder of the archive.
• Optional properties shall be assigned the value null when not used.
• For human readability the JSON object should be formatted as indented pretty print

The following snippet provides an example of the content of the header fiel

{
    "mediaType": "application/ecss-e-tm-10-25+json",
    "dataModelVersion": "2.5.0",
    "exchangeFileFormatVersion": "1.0.0",
    "creatorOrganization": {
        "iid": null,
        "name": "RHEA Group",
        "unit": "SEMT",
        "site": "Leiden, The Netherlands"
    },
    "creatorPerson": {
        "iid": "26b47595-371e-45f4-aea5-3dbb7448852f",
        "givenName": "John",
        "surname": "Doe",
        "email": "[email protected]"
    },
    "copyright": "Copyright 2018 © RHEA Group. The information contained in this file may only be used in the context of work on Programme Z by members of the Programme Z development team.",
    "createdOn": {
        "local": "2018-08-20T12:00:00+02",
        "utc": "2015-08-27T10:10:00Z"
    },
    "lastModifiedOn": null,
    "remark": "This is an example ECSS-E-TM-10-25 exchange file created by the CDP4",
    "extensions": null
}

SiteDirectory File

• The archive contains one SiteDirectory File which is named "SiteDirectory.json".
• The content of the SiteDirectory File is a JSON array of JSON objects, each JSON object is a serialized of an ECSS-E-TM-10-25 object.
• The ECSS-E-TM-10-25 objects contained in the SiteDirectory File comprise the complete composite structure (i.e. the directly and indirectly contained object graph) of an ECSS-E-TM-10-25 SiteDirectory object, with the exception of the composite structures of SiteReferenceDataLibrary and ModelReferenceDataLibrary objects.
• The SiteReferenceDataLibrary and ModelReferenceDataLibrary objects themselves are included in the SiteDirectory File, while their contained object graphs are stored in the SiteReferenceDataLibrary and ModelReferenceDataLibrary Files respectively, as specified below.

SiteReferenceDataLibrary Files

• The archive contains one SiteReferenceDataLibrary File for each SiteReferenceDataLibrary object in the SiteDirectory File.
• The SiteReferenceDataLibrary Files are located in a folder in the archive named "SiteReferenceDataLibraries".
• The name of a SiteReferenceDataLibrary File is ".json", where is the iid of the corresponding SiteReferenceDataLibrary object, a UUID v4 serialised string.
• Each SiteReferenceDataLibrary File contains a JSON array of JSON objects that is the serialisation of the complete contained composite structure of the corresponding ECSS-E-TM-10-25 SiteReferenceDataLibrary object, excluding the SiteReferenceDataLibrary object itself. The SiteReferenceDataLibrary object resides in the SiteDirectory File.

ModelReferenceDataLibrary Files

• The archive contains one ModelReferenceDataLibrary File for each ModelReferenceDataLibrary object in the SiteDirectory File.
• The ModelReferenceDataLibrary Files are located in a folder in the archive named "ModelReferenceDataLibraries".
• The name of a ModelReferenceDataLibrary File is ".json", where is the iid of the corresponding ModelReferenceDataLibrary object, a UUID serialised string.
• Each ModelReferenceDataLibrary File contains a JSON array of JSON objects that is the serialisation of the complete contained composite structure of the corresponding ECSS-E-TM-10-25 ModelReferenceDataLibrary object, excluding the ModelReferenceDataLibrary object itself. The ModelReferenceDataLibrary object resides in the SiteDirectory File.

EngineeringModel Files

• The EngineeringModel Files are located in a folder in the archive named "EngineeringModels".
• The "EngineeringModels" folder contains one EngineeringModel Folder for each EngineeringModelSetup object in the SiteDirectory File. The name of each folder is the serialized iid of the corresponding EngineeringModel object, which is the same as the serialized engineeringModelIid property of the corresponding EngineeringModelSetup object.
• Each EngineeringModel Folder contains the following:
  • One EngineeringModel File named ".json", where is the serialized iid of the corresponding EngineeringModel object. This file contains a JSON array of JSON objects that is the serialisation of the corresponding EngineeringModel object and its contained objects, excluding any Iteration object and objects it contains.
    • An Iterations Folder named "Iterations".
    • A FileRevisions Folder named "FileRevisions".
• The Iterations Folder contains one or more Iteration Files where each Iteration File is named ".json", where is the serialized iid of the corresponding Iteration object_ and contains a JSON array of JSON objects that is the serialisation of the the corresponding Iteration object and its contained objects.
• Typically at least the latest Iteration object will always be included, and optionally older Iteration objects.
• The FileRevisions Folder contains zero or more files, where each file is named by the SHA1 contentHash of the corresponding FileRevision object and the content is its byte stream. In case multiple FileRevision objects have the same SHA1 contentHash, the content is stored only once.

Extensions Folder

• The archive may contain a folder named "Extensions".
• The Extensions Folder may contain any file or folder content that is used by an implementation in addition to the standardised content as specified in the rest of this file format.
• It is recommended that the content of Extensions Folder conforms to similar JSON formats as the rest of this file format.