Semaptic Hub API

Name your JSON fields with vocabulary terms, and the hub supplies their meaning: it embeds the @semaptic object that describes every value, and converts the document to RDF.

Base URL https://semaptichub.inesctec.ptOpenAPI 3.1 — /api/openapi.json

How they fit together

Every key a vocabulary term? /api/json-to-rdf returns the RDF in one step.
Some keys are your own? /api/semaptic embeds the block, with an empty entry for each key the vocabulary does not know. Describe those (the Semaptic Builder), or rename them to terms first (the Vocabulary Aligner), then send the document to /api/rdf.
Most consumers never need RDF: the JSON with its @semaptic object is the deliverable, and the payload stays as the service wrote it.

Try it

base — the namespace your entities are minted inreport — also say which keys were described

The document

POST /api/semaptic?base=https%3A%2F%2Fdata.example.org%2Fid%2F

Documents

POST/api/semaptic— Embed the @semaptic object in a document

Every key that is a vocabulary term gets the term's template from the registry, with the templates of the nodes it introduces and the prefixes they use. Every other key gets an empty entry ("key": {}), to be described by hand; until it is, it converts as a plain literal. An existing @semaptic object is replaced. @annotations records the date and that the API assembled the block.

Body: The document, up to 10 MB.

Query	Default	Meaning
base	—	The namespace the document's entities are minted in: an absolute http(s) IRI ending in / or #.
report	false	Return { document, report } rather than the document alone.

Responses

200 The document with its @semaptic object — or, with report=true, { document, report }.
400 Not JSON, not a JSON object, or an invalid base.
413 Larger than 10 MB.
429 Too many requests from this client; see Retry-After.
503 The vocabulary registry is unavailable.

curl -X POST "https://semaptichub.inesctec.pt/api/semaptic" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

POST/api/rdf— Convert a document carrying @semaptic to RDF

The conversion the RDF Transformer runs, with the hub's datatypes. The document must carry its @semaptic object — send it to /api/semaptic first, or use /api/json-to-rdf.

Body: The document with its @semaptic object, up to 5 MB.

Query	Default	Meaning
format ttl \| nt \| rdf \| jsonld	ttl	The RDF format. Without it, the Accept header decides; Turtle by default.
base	—	The namespace the document's entities are minted in: an absolute http(s) IRI ending in / or #.
skolemize	false	Name anonymous nodes with stable IRIs, so that the graphs of several documents merge.
align	true	Link values to their instant (time:hasTime), from a time axis or a record's own timestamp.
maxArrayItems	0	Keep at most this many elements of each array (0 = all): to convert a sample of a large document.

Responses

200 The RDF.
400 Not JSON, no @semaptic object, or an invalid option.
413 Larger than 5 MB, or more than 2 million triples: convert a sample with maxArrayItems.
422 The document could not be converted.
429 Too many requests from this client; see Retry-After.
503 Busy converting other documents; see Retry-After.

curl -X POST "https://semaptichub.inesctec.pt/api/rdf" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

POST/api/json-to-rdf— Convert a plain document to RDF, when every key is a vocabulary term

The @semaptic object is assembled from the registry and the document converted in one step, as /api/semaptic then /api/rdf would. Any @semaptic object the document carries is ignored. When a key is not a vocabulary term, nothing is converted and the answer names the keys.

Body: The document, up to 5 MB.

Query	Default	Meaning
format ttl \| nt \| rdf \| jsonld	ttl	The RDF format. Without it, the Accept header decides; Turtle by default.
base	—	The namespace the document's entities are minted in: an absolute http(s) IRI ending in / or #.
skolemize	false	Name anonymous nodes with stable IRIs, so that the graphs of several documents merge.
align	true	Link values to their instant (time:hasTime), from a time axis or a record's own timestamp.
maxArrayItems	0	Keep at most this many elements of each array (0 = all): to convert a sample of a large document.

Responses

200 The RDF.
400 Not JSON, not a JSON object, or an invalid option.
413 Larger than 5 MB, or more than 2 million triples.
422 Not every key is a vocabulary term: nothing was converted.
429 Too many requests from this client; see Retry-After.
503 The registry is unavailable, or the converter is busy.

curl -X POST "https://semaptichub.inesctec.pt/api/json-to-rdf" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

Vocabulary

GET/api/parameters— The vocabulary's terms

Query	Default	Meaning
category	—	Only the terms in this category.

Responses

200 The terms, by name.
500 The registry is unavailable.

curl "https://semaptichub.inesctec.pt/api/parameters"

GET/api/categories— The categories terms are grouped in

Responses

200 The categories.
500 The registry is unavailable.

curl "https://semaptichub.inesctec.pt/api/categories"

GET/api/ontologies— The registered prefixes and their namespaces

Responses

200 Prefix and namespace IRI of every ontology the templates may cite.
500 The registry is unavailable.

curl "https://semaptichub.inesctec.pt/api/ontologies"

GET/api/semantics— The templates of one or more terms, as rows

Each row is one statement of a term's template (subject, predicate, object), including the rows of the nodes it introduces.

Query	Default	Meaning
parameter *	—	A term; repeat for several (at most 500).

Responses

200 The rows.
400 No term given, or more than 500.
500 The registry is unavailable.

curl "https://semaptichub.inesctec.pt/api/semantics"

GET/api/vocabulary— The whole vocabulary as RDF

Also served at the vocabulary's namespace, https://semaptichub.inesctec.pt/vocabulary/, to requests that prefer RDF.

Query	Default	Meaning
format ttl \| nt \| rdf	ttl	Without it, the Accept header decides; Turtle by default.

Responses

200 The vocabulary.

curl "https://semaptichub.inesctec.pt/api/vocabulary"

POST/api/suggest-parameter— Suggest a term for the vocabulary

Stored for an administrator to review; the email is used only to follow up on the suggestion.

Responses

200 Saved for review.
400 A field is missing, the email is invalid, or the term already exists.
409 Already suggested and waiting for review.
500 The suggestion could not be saved.

curl -X POST "https://semaptichub.inesctec.pt/api/suggest-parameter" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

The document endpoints send CORS headers, so a page on any site can call them, and are rate-limited per client. Load /api/openapi.json into Swagger UI, Postman or a code generator to get a client.