Outdated version

You are browsing the docs for Nexus v1.10.x, the latest release is available here

Schemas

Schemas are rooted in the /v1/schemas/{org_label}/{project_label} collection. They define a set of rules and constraints using SHACL. Once those schemas are present, other resources can be created against them. Those resources won’t be successfully created unless they match the required constraints defined on the schema.

Each schema…

  • belongs to a project identifier by the label {project_label}
  • inside an organization identifier by the label {org_label}
  • it is validated against the SHACL schema (version 20170720).
Authorization notes

When modifying schemas, the caller must have schemas/write permissions on the current path of the project or the ancestor paths.

When reading schemas, the caller must have resources/read permissions on the current path of the project or the ancestor paths.

Please visit Authentication & authorization section to learn more about it.

Note

From Delta v1.5, remote contexts and owl:imports are only resolved during creates and updates. That means that when those get updated, the schemas importing them must be also updated to take the changes into account.

Indexing

All the API calls modifying a schema (creation, update, tagging, deprecation) can specify whether the schema should be indexed synchronously or in the background. This behaviour is controlled using indexing query param, which can be one of two values:

  • async - (default value) the schema will be indexed asynchronously
  • sync - the schema will be indexed synchronously and the API call won’t return until the indexing is finished

Create using POST

POST /v1/schemas/{org_label}/{project_label}
  {...}

The json payload:

  • If the @id value is found on the payload, this @id will be used.
  • If the @id value is not found on the payload, an @id will be generated as follows: base:{UUID}. The base is the prefix defined on the resource’s project ({project_label}).

Example

Request
sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/schemas/myorg/myproj" \
     -d \
'{
  "@context": {
      "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
      "ex": "http://localhost:9999/"
  },
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}'
Payload
source{
  "@context": {
    "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://localhost:9999/"
  },
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:54:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Create using PUT

This alternative endpoint to create a schema is useful in case the json payload does not contain an @id but you want to specify one. The @id will be specified in the last segment of the endpoint URI.

PUT /v1/schemas/{org_label}/{project_label}/{schema_id}
  {...}

Note that if the payload contains an @id different from the {schema_id}, the request will fail.

Example

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c" \
     -d \
'{
  "@context":  {
      "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
      "ex": "http://localhot:9999/"
  },
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}'
Payload
source{
  "@context": {
    "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://localhost:9999/"
  },
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:54:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:54:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Update

This operation overrides the payload.

In order to ensure a client does not perform any changes to a resource without having had seen the previous revision of the resource, the last revision needs to be passed as a query parameter.

PUT /v1/schemas/{org_label}/{project_label}/{schema_id}?rev={previous_rev}
  {...}

… where {previous_rev} is the last known revision number for the schema.

Example

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c?rev=1" \
     -d \
'{
  "@context": {
      "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
      "ex": "http://example.com/"
  },
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}'
Payload
source{
  "@context": {
    "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://localhost:9999/"
  },
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:56:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Refresh

This operation refreshes the compacted and expanded representations of the schema.

This is equivalent of doing an update with the same source as the last revision of the schema. It is useful when schemas imports have changed, in order for the changes to be reflected in the schema.

PUT /v1/schemas/{org_label}/{project_label}/{schema_id}

Example

Request
sourcecurl -X PUT \
     "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/refresh"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:56:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Tag

Links a schema revision to a specific name.

Tagging a schema is considered to be an update as well.

POST /v1/schemas/{org_label}/{project_label}/{schema_id}/tags?rev={previous_rev}
  {
    "tag": "{name}",
    "rev": {rev}
  }

… where

  • {previous_rev}: Number - is the last known revision for the resolver.
  • {name}: String - label given to the schemas at specific revision.
  • {rev}: Number - the revision to link the provided {name}.

Example

Request
sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/schemas/myorg/myproj/myschema/e1729302-35b8-4d80-97b2-d63c984e2b5c/tags?rev=2" \
     -d \
'{
  "tag": "mytag",
  "rev": 1
}'
Payload
source{
  "tag": "mytag",
  "rev": 1
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:58:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Remove tag

Removes a given tag.

Removing a tag is considered to be an update as well.

DELETE /v1/schemas/{org_label}/{project_label}/{schema_id}/tags/{tag_name}?rev={previous_rev}

… where

  • {previous_rev}: is the last known revision number for the resource.
  • {tag_name}: String - label of the tag to remove.

Example

Request
sourcecurl -X DELETE \
     "http://localhost:8080/v1/schemas/myorg/myproj/myschema/e1729302-35b8-4d80-97b2-d63c984e2b5c/tags/mytag?rev=2"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T14:58:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Deprecate

Locks the schema, so no further operations can be performed. It also deletes the schema from listing/querying results.

Deprecating a schema is considered to be an update as well. 

DELETE /v1/schemas/{org_label}/{project_label}/{schema_id}?rev={previous_rev}

… where {previous_rev} is the last known revision number for the schema.

Example

Request
sourcecurl -X DELETE \
     "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c?rev=3"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T15:05:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Undeprecate

Unlocks the schema, so further operations can be performed. It adds the schema to listing/querying results again.

Undeprecating a schema is considered to be an update as well. 

PUT /v1/schemas/{org_label}/{project_label}/{schema_id}/undeprecate?rev={previous_rev}

… where {previous_rev} is the last known revision number for the schema.

Example

Request
sourcecurl -X PUT \
     "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/undeprecate?rev=4"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 5,
  "_deprecated": true,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T15:05:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

Fetch

GET /v1/schemas/{org_label}/{project_label}/{schema_id}?rev={rev}&tag={tag}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional.

{rev} and {tag} fields cannot be simultaneously present.

Example

Request
sourcecurl "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/schemas-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    {
      "ex": "http://localhost:9999/",
      "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    },
    "https://bluebrain.github.io/nexus/contexts/shacl-20170720.json"
  ],
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "NodeShape",
      "nodeKind": "BlankNode:OrIRI",
      "property": [
        {
          "datatype": "xsd:string",
          "minCount": 1,
          "path": "ex:name"
        },
        {
          "datatype": "xsd:boolean",
          "minCount": 1,
          "path": "ex:bool"
        },
        {
          "datatype": "xsd:integer",
          "minCount": 1,
          "path": "ex:number"
        }
      ],
      "targetClass": "ex:Custom"
    }
  ],
  "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "http://localhost:8080/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2021-04-17T14:55:42.939Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
  "_updatedAt": "2021-04-17T15:05:42.939Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
}

If the redirect to Fusion feature is enabled and if the Accept header is set to text/html, a redirection to the fusion representation of the resource will be returned.

Fetch original payload

GET /v1/schemas/{org_label}/{project_label}/{schema_id}/source?rev={rev}&tag={tag}&annotate={annotate}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional.
  • {annotate}: Boolean - annotate the response with the schema metadata.

{rev} and {tag} fields cannot be simultaneously present.

If {annotate} is set, the metadata is injected alongside with the original payload where the ones from the original payload take precedence. The context in the original payload is also amended with the metadata context.

Example

Request
sourcecurl "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/source"
Response
source{
  "@context": {
    "this": "http://localhost:8080/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://localhost:9999/"
  },
  "@id": "http://localhost:8080/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "shapes": [
    {
      "@id": "this:MyShape",
      "@type": "sh:NodeShape",
      "nodeKind": "sh:BlankNodeOrIRI",
      "targetClass": "ex:Custom",
      "property": [
        {
          "path": "ex:name",
          "datatype": "xsd:string",
          "minCount": 1
        },
        {
          "path": "ex:number",
          "datatype": "xsd:integer",
          "minCount": 1
        },
        {
          "path": "ex:bool",
          "datatype": "xsd:boolean",
          "minCount": 1
        }
      ]
    }
  ]
}

Fetch tags

GET /v1/schemas/{org_label}/{project_label}/{schema_id}/tags?rev={rev}&tag={tag}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional.

{rev} and {tag} fields cannot be simultaneously present.

Example

Request
sourcecurl "http://localhost:8080/v1/schemas/myorg/myproj/myschema/e1729302-35b8-4d80-97b2-d63c984e2b5c/tags?rev=2"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/tags.json",
  "tags": [
    {
      "rev": 1,
      "tag": "mytag"
    }
  ]
}

List

There are three available endpoint to list schemas in different scopes.

Within a project

GET /v1/schemas/{org_label}/{project_label}?from={from}
                                           &size={size}
                                           &deprecated={deprecated}
                                           &rev={rev}
                                           &type={type}
                                           &createdBy={createdBy}
                                           &updatedBy={updatedBy}
                                           &q={search}
                                           &sort={sort}
                                           &aggregations={aggregations}

Within an organization

This operation returns only schemas from projects defined in the organisation {org_label} and where the caller has the resources/read permission.

GET /v1/schemas/{org_label}?from={from}
                           &size={size}
                           &deprecated={deprecated}
                           &rev={rev}
                           &type={type}
                           &createdBy={createdBy}
                           &updatedBy={updatedBy}
                           &q={search}
                           &sort={sort}
                           &aggregations={aggregations}

Within all projects

This operation returns only schemas from projects defined the organisation {org_label} and where the caller has the resources/read permission.

GET /v1/schemas?from={from}
               &size={size}
               &deprecated={deprecated}
               &rev={rev}
               &type={type}
               &createdBy={createdBy}
               &updatedBy={updatedBy}
               &q={search}
               &sort={sort}
               &aggregations={aggregations}

Parameter description

  • {from}: Number - is the parameter that describes the offset for the current query; defaults to 0
  • {size}: Number - is the parameter that limits the number of results; defaults to 20
  • {deprecated}: Boolean - can be used to filter the resulting schemas based on their deprecation status
  • {rev}: Number - can be used to filter the resulting schemas based on their revision value
  • {type}: Iri - can be used to filter the resulting schemas based on their @type value. This parameter can appear multiple times, filtering further the @type value.
  • {createdBy}: Iri - can be used to filter the resulting schemas based on their creator
  • {updatedBy}: Iri - can be used to filter the resulting schemas based on the person which performed the last update
  • {search}: String - can be provided to select only the schemas in the collection that have attribute values matching (containing) the provided string
  • {sort}: String - can be used to sort schemas based on a payloads’ field. This parameter can appear multiple times to enable sorting by multiple fields. The default is done by _createdBy and @id.
  • {aggregations}: Boolean - if true then the response will only contain aggregations of the @type and _project fields; defaults to false. See Aggregations.

Example

Request
sourcecurl "http://localhost:8080/v1/schemas/myorg/myproj"
Response
source{
  "@context" : [
    "https://bluebrain.github.io/nexus/contexts/metadata.json",
    "https://bluebrain.github.io/nexus/contexts/search.json",
    "https://bluebrain.github.io/nexus/contexts/search-metadata.json"
  ],
  "_total": 1,
  "_results": [
    {
      "@id": "https://bluebrain.github.io/nexus/schemas/myschema2",
      "@type": "https://bluebrain.github.io/nexus/vocabulary/Schema",
      "_incoming": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
      "_outgoing": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
      "_self": "http://localhost:8080/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
      "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
      "_project": "http://localhost:8080/v1/projects/myorg/myproj",
      "_rev": 4,
      "_deprecated": true,
      "_createdAt": "2021-04-17T14:55:42.939Z",
      "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/john",
      "_updatedAt": "2021-04-17T15:05:42.939Z",
      "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/john"
    }
  ],
  "_next": "http://localhost:8080/v1/schemas/myorg/myproj?after=%5B1559045718752,%22https://bluebrain.github.io/nexus/schemas/myschema29%22%5D"
}

Server Sent Events

From Delta 1.5, it is possible to fetch SSEs for all schemas or just schemas in the scope of an organization or a project.

GET /v1/schemas/events                              # for all schema events in the application
GET /v1/schemas/{org_label}/events                  # for schema events in the given organization
GET /v1/schemas/{org_label}/{project_label}/events  # for schema events in the given project

The caller must have respectively the events/read permission on /, {org_label} and {org_label}/{project_label}.

  • {org_label}: String - the selected organization for which the events are going to be filtered
  • {project_label}: String - the selected project for which the events are going to be filtered
  • Last-Event-Id: String - optional HTTP Header that identifies the last consumed resource event. It can be used for cases when a client does not want to retrieve the whole event stream, but to start after a specific event.
Note

The event type for schemas SSEs have been changed so that it is easier to distinguish them from other types of resources.

Example

Request
sourcecurl "http://localhost:8080/v1/schemas/events"
Response
sourcedata:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/shacl-20170720.json"],"@type":"SchemaCreated","_constrainedBy":"https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl","_instant":"2021-04-17T14:55:42.939Z","_project":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/myid2","_rev":1,"_schemaId":"https://bluebrain.github.io/nexus/vocabulary/myid2","_source":{"@context":{"nxv":"https://bluebrain.github.io/nexus/vocabulary/"},"@type":"Schema","shapes":[{"@id":"nxv:MyShape","@type":"NodeShape","nodeKind":"sh:BlankNodeOrIRI","property":[{"@id":"nxv:NameProperty","datatype":"xsd:string","minCount":1,"path":"nxv:name"},{"@id":"nxv:NumberProperty","datatype":"xsd:integer","minCount":1,"path":"nxv:number"},{"@id":"nxv:PathProperty","datatype":"xsd:boolean","minCount":1,"path":"nxv:bool"}],"targetClass":"nxv:Custom"}]},"_subject":"http://localhost:8080/v1/realms/wonderland/users/alice","_types":["https://bluebrain.github.io/nexus/vocabulary/Schema"]}
event:SchemaCreated
id:1

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/shacl-20170720.json"],"@type":"SchemaUpdated","_constrainedBy":"https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl","_instant":"2021-04-17T14:55:42.939Z","_project":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/myid","_rev":2,"_schemaId":"https://bluebrain.github.io/nexus/vocabulary/myid","_source":{"@context":{"nxv":"https://bluebrain.github.io/nexus/vocabulary/"},"@type":"Schema","shapes":[{"@id":"nxv:MyShape","@type":"NodeShape","nodeKind":"sh:BlankNodeOrIRI","property":[{"@id":"nxv:NameProperty","datatype":"xsd:string","minCount":1,"path":"nxv:name"},{"@id":"nxv:NumberProperty","datatype":"xsd:double","minCount":1,"path":"nxv:number"},{"@id":"nxv:PathProperty","datatype":"xsd:boolean","minCount":1,"path":"nxv:bool"}],"targetClass":"nxv:Custom"}]},"_subject":"http://localhost:8080/v1/anonymous","_types":["https://bluebrain.github.io/nexus/vocabulary/Schema"]}
event:SchemaUpdated
id:2

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/shacl-20170720.json"],"@type":"SchemaDeprecated","_constrainedBy":"https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl","_instant":"2021-04-17T14:55:42.939Z","_project":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/myid","_rev":4,"_schemaId":"https://bluebrain.github.io/nexus/vocabulary/myid","_subject":"http://localhost:8080/v1/anonymous","_types":["https://bluebrain.github.io/nexus/vocabulary/Schema"]}
event:SchemaDeprecated
id:3

data:{"@context":["https://bluebrain.github.io/nexus/contexts/metadata.json","https://bluebrain.github.io/nexus/contexts/shacl-20170720.json"],"@type":"SchemaTagAdded","tag":"mytag","targetRev":1,"_constrainedBy":"https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl","_instant":"2021-04-17T14:55:42.939Z","_project":"http://localhost:8080/v1/projects/myorg/myproject","_resourceId":"https://bluebrain.github.io/nexus/vocabulary/myid2","_rev":2,"_schemaId":"https://bluebrain.github.io/nexus/vocabulary/myid2","_subject":"http://localhost:8080/v1/anonymous","_types":["https://bluebrain.github.io/nexus/vocabulary/Schema"]}
event:SchemaTagAdded
id:4
v1.10.x