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.
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}
. Thebase
is theprefix
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 to0
{size}
: Number - is the parameter that limits the number of results; defaults to20
{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" }