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).

Access to resources in the system depends on the access control list set for them. Depending on the access control list, a caller may need to prove its identity by means of an access token passed to the Authorization header (Authorization: Bearer {token}). Please visit Authentication to learn more about how to retrieve an access token.

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.

Create a schema 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
curl -XPOST -H "Content-Type: application/json" "https://nexus.example.com/v1/schemas/myorg/myproj" -d \
'{
  "@context": {
      "this": "https://nexus.example.com/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
      "ex": "http://example.com/"
  },
  "@id": "https://nexus.example.com/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
{
  "@context": {
    "this": "https://nexus.example.com/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://example.com/"
  },
  "@id": "https://nexus.example.com/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
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:54:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Create a schema 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
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c" -d \
'{
  "@context":  {
      "this": "https://nexus.example.com/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
{
  "@context": {
    "this": "https://nexus.example.com/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://example.com/"
  },
  "@id": "https://nexus.example.com/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
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 1,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:54:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:54:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Update a schema

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
curl -XPUT -H "Content-Type: application/json" "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c?rev=1" -d \
'{
  "@context": {
      "this": "https://nexus.example.com/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
{
  "@context": {
    "this": "https://nexus.example.com/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    "ex": "http://example.com/"
  },
  "@id": "https://nexus.example.com/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
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 2,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:55:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:56:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Tag a schema

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
curl -XPOST -H "Content-Type: application/json" "https://nexus.example.com/v1/schemas/myorg/myproj/myschema/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/tags?rev=2" -d \
'{
  "tag": "mytag",
  "rev": 1
}'
Payload
{
  "tag": "mytag",
  "rev": 1
}
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 3,
  "_deprecated": false,
  "_createdAt": "2018-09-17T14:55:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T14:58:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Deprecate a schema

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
curl -XDELETE "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c?rev=5"
Response
{
  "@context": "https://bluebrain.github.io/nexus/contexts/resource.json",
  "@id": "https://nexus.example.com/v1/resources/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "@type": "Schema",
  "_incoming": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 6,
  "_deprecated": true,
  "_createdAt": "2018-09-17T14:55:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T15:05:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Fetch a schema

When fetching a schema, the response format can be chosen through HTTP content negotiation, using the Accept HTTP header.

  • application/ld+json: JSON-LD output response. Further specifying the query parameter format=compacted|expanded will provide with the JSON-LD compacted document form or the expanded document form.
  • application/n-triples: RDF n-triples response, as defined by the w3.
  • text/vnd.graphviz: A DOT response.

If Accept: */* HTTP header is present, Nexus defaults to the JSON-LD output in compacted form.

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
curl "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c"
Response
{
  "@context": [
    {
      "ex": "http://example.com/",
      "this": "https://nexus.example.com/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    },
    "https://bluebrain.github.io/nexus/contexts/shacl-20170720.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/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": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/incoming",
  "_outgoing": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/outgoing",
  "_self": "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c",
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/shacl-20170720.ttl",
  "_project": "https://nexus.example.com/v1/projects/myorg/myproj",
  "_rev": 4,
  "_deprecated": true,
  "_createdAt": "2018-09-17T14:55:42.939Z",
  "_createdBy": "https://nexus.example.com/v1/realms/myrealm/users/john",
  "_updatedAt": "2018-09-17T15:05:42.939Z",
  "_updatedBy": "https://nexus.example.com/v1/realms/myrealm/users/john"
}

Fetch a schema original payload

GET /v1/schemas/{org_label}/{project_label}/{schema_id}/source?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
curl "https://nexus.example.com/v1/schemas/myorg/myproj/base:e1729302-35b8-4d80-97b2-d63c984e2b5c/source"
Response
{
  "@context": [
    {
      "ex": "http://example.com/",
      "this": "https://nexus.example.com/v1/schemas/myorg/myproj/e1729302-35b8-4d80-97b2-d63c984e2b5c/shapes",
    },
    "https://bluebrain.github.io/nexus/contexts/shacl-20170720.json",
    "https://bluebrain.github.io/nexus/contexts/resource.json"
  ],
  "@id": "https://nexus.example.com/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"
    }
  ]
}

List schemas

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}

where…

  • {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

Example

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