Model Catalog API (v1)

Download OpenAPI specification:Download

API to manage semantic models and namespaces for a Model Catalog

Conditional Headers

Certain resources are supporting conditional headers like If-Match or If-Modified-Since which makes a request conditional. This allows to further optimize requests e.g. to avoid the download of model elements if it has not been modified since the date defined by If-Modified-Since.

Further it is possible to combine headers by defining it separately. Using 'curl' this looks like:

curl ... -H 'If-Match: {hash}' -H 'If-Modified-Since: {date-time}'

Authentication

The API offers currently one form of authentication:

  • OAuth2 - An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

HAL Format

The API uses the HAL Format for HATEOAS see https://de.wikipedia.org/wiki/Hypertext_Application_Language

Package

Upload one or more namespaces (RDF/Turtle files) as a package (zip archive) There are follow restriction. For content-type multipart/form-data you can upload 1MB. If you use directly the content-type application/zip there zip cannot be larger than 128 KB.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Request Body schema: multipart/form-data
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Namespace

Get all namespaces

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

query Parameters
page
integer >= 0
Default: 0

Index of the current page

pageSize
integer [ 1 .. 500 ]
Default: 500

Responses

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Get the Namespace and included SAMM concepts (Aspect, Entities, Properties, etc.)

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
NamespaceUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0

Qualified identifier for a versioned Namespace

query Parameters
fully-resolved
boolean
Default: false

Enforce to fully resolve external references and return it as one TTL

Responses

Response samples

Content type
<<binary content>>

Deletes the namespace

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
NamespaceUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0

Qualified identifier for a versioned Namespace

Responses

Gets the namespace on which given namespace depends on

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
NamespaceUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0

Qualified identifier for a versioned Namespace

Responses

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Get the state of the namespace

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
NamespaceUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0

Qualified identifier for a versioned Namespace

Responses

Response samples

Content type
application/json
"RELEASED"

Change the namespace state

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
NamespaceUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0

Qualified identifier for a versioned Namespace

Request Body schema: application/json
state
required
string (StateDto)
Enum: "DRAFT" "RELEASED" "DEPRECATED"

The possible workflow states a namespace can have

Responses

Request samples

Content type
application/json
{
  • "state": "RELEASED"
}

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Get the next states for the namespace

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
NamespaceUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0

Qualified identifier for a versioned Namespace

Responses

Response samples

Content type
application/json
"RELEASED"

Model

Get the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
application/json
{
  • "urn": "urn:samm:com.mycompany:1.0.0#Movement",
  • "version": "1.0.0",
  • "name": "Movement",
  • "state": "RELEASED",
  • "description": {
    }
}

Get the raw Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:samm:com.mycompany.test:1.2.0#BooleanEntity> a <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#Entity> ;
<urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#properties> ( <urn:samm:com.bosch.dts.catalog.test:1.2.0#testBoolean> ) .

<urn:samm:com.mycompany.test:1.2.0#BooleanTestCharacteristic> a <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#Characteristic> ;
<urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#dataType> xsd:boolean ;
<urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#preferredName> "BooleanTestCharacteristic"@en .

Get the diagram for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

query Parameters
locale
string
Default: "en"

Locale to resolve e.g. preferred name and description

Responses

Response samples

Content type
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" height="867.25pt" width="1079.0pt" viewBox="0.00 0.00 1079.0 867.25">
  <g id="graph_root" class="graph" transform="scale(1.0 1.0) rotate(0)">
  </g>
</svg>

Get the documentation for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

query Parameters
locale
string
Default: "en"

Locale to resolve e.g. preferred name and description

Responses

Response samples

Content type
<!doctype html>
<html lang="en">
  <head>
    <meta http-equiv="content-type" content="text/html; chartset=utf-8">
    <title>Documentation TestAspect</title>
  </head>
  <body class="flex">
    <header class="fixed w-full flex flex-col z-10 top-0 bg-white">
      <h1 id="TestAspect">Aspect Model TestAspect</h1>
      <div class='pb-4'>urn:samm:com.mycompany.test:1.2.0#TestAspect</div>
    </header>
    <div class="pb-5">
        A test Aspect
    </div>
  </body>
</html>

Get the JSON Schema for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
{
  • "description": "A test Aspect",
  • "type": "object",
  • "components": {
    },
  • "properties": {
    },
  • "required": [
    ]
}

Get the example payload for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
{
  • "testBoolean": true,
  • "secondTestBoolean": false
}

Get the Open api description

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type

Get the AASX format for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
<<binary content>>

Get the AAS JSON format for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
{
  • "assetAdministrationShells": [
    ],
  • "conceptDescriptions": [ ]
}

Get the AAS XML format for the Aspect Model

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

urn
required
AspectModelUrn
Example: urn%3Asamm%3Acom.mycompany%3A1.0.0%23Movement

Encoded qualified identifier of the Aspect Model

Responses

Response samples

Content type
<?xml version='1.0' encoding='UTF-8'?>
<aas:environment xmlns:aas="https://admin-shell.io/aas/3/0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://admin-shell.io/aas/3/0 AAS.xsd">
  <aas:assetAdministrationShells>
      <aas:assetAdministrationShell>
        <aas:idShort>defaultAdminShell</aas:idShort>
        <aas:description>
          <aas:langStringTextType>
            <aas:language>en</aas:language>
            <aas:text>defaultAdminShell</aas:text>
          </aas:langStringTextType>
        </aas:description>
        <aas:administration/>
        <aas:id>urn:samm:com.mycompany.test:1.2.0#TestAspect</aas:id>
        <aas:assetInformation>
          <aas:assetKind>Type</aas:assetKind>
        </aas:assetInformation>
        <aas:submodels/>
      </aas:assetAdministrationShell>
    </aas:assetAdministrationShells>
    <aas:conceptDescriptions/>
</aas:environment>

Search

Search namespaces

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Request Body schema: application/json
page
required
integer >= 0
Default: 0

Index of the current page

pageSize
required
integer [ 1 .. 500 ]
Default: 500

Number of items per page

namespacePattern
string or null [ 1 .. 100 ] characters

Search for a namespace. Wildcard is supported at the end only.

state
string or null
Enum: "DRAFT" "RELEASED" "DEPRECATED"

The possible workflow states a namespace can have

object or null

Search within the range of versions

Responses

Request samples

Content type
application/json
{
  • "page": 0,
  • "pageSize": 500,
  • "namespacePattern": "move*",
  • "state": "RELEASED",
  • "versionRangePattern": {
    }
}

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Search SAMM elements like Entities, Aspects, etc.

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Request Body schema: application/json
page
required
integer >= 0
Default: 0

Index of the current page

pageSize
required
integer [ 1 .. 500 ]
Default: 500

Number of items per page

modelElementNamePattern
string or null [ 3 .. 100 ] characters

Search for a name. Wildcard is supported at the end only.

object (ModelElementPreferredNamePatternDto)

Search for preferred name. Wildcard is supported at the end only.

state
string (StateDto)
Enum: "DRAFT" "RELEASED" "DEPRECATED"

The possible workflow states a namespace can have

object (VersionRangeSearchPatternDto)

Search within the range of versions

modelElementTypes
Array of strings or null (ModelElementTypeDto) unique
Items Enum: "ASPECT" "OPERATION" "EVENT" "PROPERTY" "ENTITY" "CHARACTERISTIC" "CONSTRAINT"

Search for element types.

namespacePattern
string or null [ 1 .. 100 ] characters

Search for one or more namespaces. Wildcard is supported at the end only.

Responses

Request samples

Content type
application/json
{
  • "page": 0,
  • "pageSize": 500,
  • "modelElementNamePattern": "move*",
  • "modelElementPreferredNamePattern": {
    },
  • "state": "RELEASED",
  • "versionRangePattern": {
    },
  • "modelElementTypes": [
    ],
  • "namespacePattern": "com.bosch.*"
}

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Setting

Delete the whitelisted namespace

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

prefix
required
string

Value of a namespace

Responses

Get all whitelisted namespaces for the tenant

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Responses

Response samples

Content type
application/json
{
  • "totalItems": 0,
  • "currentPage": 0,
  • "totalPages": 0,
  • "itemCount": 0,
  • "items": [
    ]
}

Reserve a namespace for the tenant

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Request Body schema: application/json

The information is required to preserve a namespace

prefix
required
string [ 1 .. 255 ] characters ^([a-z0-9()+,\-.:=@;$_!*]|%[0-9a-fA-F]{2})+$

Responses

Request samples

Content type
application/json
{
  • "prefix": "com.mycompany"
}

Response samples

Content type
application/json
{
  • "prefix": "com.mycompany"
}

Deletes all data related to a tenant

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Responses

Generates artifacts for the tenant

Authorizations:
macma
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}