This specification defines Hyperdata, an extension to JSON and IRI that adds classes, IRI identifiers, namespaces, and shared schemas to JSON objects. It is designed to enhance interoperability, data linking, and the self-descriptiveness of JSON data.
Hyperdata is designed to layer on simply to existing JSON data, by adding a #class
:
{
"#class": "https://example.com/schema#Article",
"title": "Introduction to Hyperdata"
}
Doing this specifies the following values via implicit derivation:
object class IRI: https://example.com/schema#Article (full-IRI)
namespace IRI: https://example.com/schema# (ns-IRI)
object property IRI: https://example.com/schema#title (full-IRI)
schema document IRI: https://example.com/schema (base-IRI)
short form name-fragments: Article, title (name-fragment)
The expectation is that when you dereference the schema document base-IRI
of https://example.com/schema
(for example via HTTP GET), a successful response will be a Hyperdata document describing the schema within the established https://example.com/schema#
namespace.
The dereferenced schema document is expected to specify:
- the
Article
class, described by an object with an#id
value ofhttps://example.com/schema#Article
, and - the named properties of the
Article
class, such astitle
, which would be described by an object with an#id
value ofhttps://example.com/schema#title
.
In this manner, the Article
class and its title
property are universally and unambiguously named within the IRI space, allowing shared understanding of readily accessible Hyperdata.
By adding an #id
to the previous example, it can also be universally named within the IRI space, allowing it to be referenced and dereferenced within the web of Hyperdata.
{
"#namespace": "https://example.com/schema#",
"#class": "Article",
"#id": "https://example.com/hyperdata-introduction#description",
"title": "Introduction to Hyperdata"
}
Again, the expectation is that when you dereference the implicitly derived document base-IRI
of https://example.com/hyperdata-introduction
, a successful response will include the above example Hyperdata object. This example introduces all three JSON property extensions defined by Hyperdata: #namespace
, #class
, #id
, and the short form name-fragment style.
Hyperdata is designed to follow the common single class based inheritance model of class Person extends Agent
, however so as not to constrain its usage, object property names may be either a name-fragment
as in previous examples, or a full-IRI
. Usage of a full-IRI
enables a mixin style composition of Hyperdata object descriptions.
{
"#namespace": "https://example.com/schema#",
"#class": "Article",
"#id": "https://example.com/hyperdata-introduction#description",
"title": "Introduction to Hyperdata",
"https://example.com/version#sha256": "c61379b9379dbbea76341ac49e1ea5e85b9a441053a404f42d16cd2c2db81959"
}
In this example, the Hyperdata includes an object property name https://example.com/version#sha256
from a different namespace (https://example.com/version#
) to the default defined for the object (https://example.com/schema#
).
- Value Space:
full-IRI
- Lexical Space:
name-fragment
ORfull-IRI
- Description: Specifies the full-IRI of the class of this object.
- Behavior:
- If the value of
#class
is afull-IRI
, the value of#namespace
MUST be set to the computedns-IRI
.- Example:
{"#class": "https://example.com/schema#Person"}
entails{"#namespace": "https://example.com/schema#"}
- Example:
- If the value of
#class
is anname-fragment
, the value MUST be appended to the in-scope#namespace
to compute it'sfull-IRI
value.- Example:
{"#namespace": "https://example.com/schema#", "#class": "Person"}
entails afull-IRI
ofhttps://example.com/schema#Person
- Example:
- If the value of
- Value Space:
ns-IRI
- Lexical Space:
#
ORns-IRI
- Description: Specifies the namespace of the current object and its children, unless they define a different namespace explicitly via
#namespace
or implicitly via afull-IRI
#class
. - Behavior:
- If not defined on the current in-scope object, it MUST be inherited from the parent object.
- If the value of
#class
is afull-IRI
, thens-IRI
value specified by this#namespace
MUST be ignored.
- Value Space:
full-IRI
- Lexical Space:
name-fragment
ORfull-IRI
- Description: Potentially establishes a unique universally quantified
full-IRI
for the property. - Behavior:
- If the value is an
name-fragment
, the value MUST be appened to the in-scope#namespace
to compute its potentialfull-IRI
value.- Example:
{"#namespace": "https://example.com/schema#", "name": "Jon Doe"}
entails afull-IRI
ofhttps://example.com/schema#name
- Example:
- If the
full-IRI
cannot be determined to have a Hyperdata description after successfully dereferencing the associated Hyperdata document or some other out of band method, it should be treated as traditional JSON object property name (it's lexical string formname-fragment
). - If the
full-IRI
belongs to a different Hyperdata namespace than the current in-scope#namespace
, the property MAY be treated as a Mixin. - If the
full-IRI
belongs to a different#class
than the one specified for the in-scope object, the property MAY be treated as a Mixin.
- If the value is an
- Value Space:
ns-IRI
ORfull-IRI
- Lexical Space:
ns-IRI
ORfull-IRI
OR#
OR (#
name-fragment
) - Description: Establishes a unique universally quantified
IRI
for the object to which this property belongs, and which the object describes. - Behavior:
- If not defined on the current in-scope object, the object SHOULD be considered as existentially quantified.
- If the lexical space is
#
OR (#
name-fragment
):- a
full-IRI
SHOULD be formed by appending it to abase-IRI
established by common out of band methods, such as the IRI used in a successful HTTP GET dereference which provided the Hyperdata document. - The current in-scope namespace
ns-IRI
MUST NOT be considered when resolving it.
- a
A Hyperdata Document is a JSON document that can be dereferenced using a unique identifier known as the base-IRI
.
When accessed over HTTP, the document should be served with the media type application/json
.
base-IRI
- a dereferencable IRI that does not include a#name-fragment
.https://example.com/schema
In a Hyperdata Document, the namespace it provides is identified by a ns-IRI
. This defines a #namespace
within which Things, Properties, and Classes are named and described.
ns-IRI
- a namespace IRI which always ends with a#
.https://example.com/schema#
In Hyperdata, Things, Properties, or Classes are given canonical full-IRI
names.
full-IRI
- an IRI that ends with a#name-fragment
.https://example.com/schema#Person
,https://example.com/schema#name
Within a Hyperdata document, a short form name-fragment
can be used as a more concise way to denote a full-IRI
when combined with a #namespace
.
name-fragment
- a shorthand syntax used within Hyperdata documents to represent afull-IRI
.{"#namespace": "https://example.com/schema#", "#class": "Person", "name": "Jon Doe"}
Hyperdata extends the Internationalized Resource Identifiers (IRIs) - RFC3987 ABNF with the following four terms, for use in Hyperdata.
base-IRI = scheme ":" ihier-part [ "?" iquery ]
ns-IRI = base-IRI "#"
full-IRI = ns-IRI name-fragment
name-fragment = 1*( ipchar / "/" / "?" )
Hyperdata introduces a strict subset of three IRI forms, each a valid IRI form, which enable implicit derivation of both the namespace's ns-IRI
, and the Hyperdata document's base-IRI
from a single full-IRI
.
To derive a ns-IRI
from a full-IRI
, remove everything after the #
.
https://example.com/schema#Person to https://example.com/schema#
To derive a base-IRI
from a full-IRI
or an ns-IRI
, remove the #
and any characters following it.
https://example.com/schema#Person OR https://example.com/schema# to https://example.com/schema
To combine a full-IRI
from a ns-IRI
and a name-fragment
, append the name-fragment
to the ns-IRI
.
https://example.com/schema# + Person = https://example.com/schema#Person
Given a #class
value of https://example.com/schema#Person
, we can implicitly determine the #namespace
to be https://example.com/schema#
and the Hyperdata document's dereferenceable base-IRI
to be https://example.com/schema
.
Consequently:
{"#namespace": "https://example.com/schema#", "#class": "Person", "name": "Jon Doe"}
can succinctly be represented as:
{"#class": "https://example.com/schema#Person", "name": "Jon Doe"}
and agents can attempt to dereference the base-IRI
to obtain the Hyperdata schema:
> GET /schema HTTP/1.1
> Host: example.com
> Accept: application/json