1.1 Status of this document

JSKOS is currently being developed as part of project coli-conc. The JSKOS specification is hosted at http://gbv.github.io/jskos/ in the public GitHub repository https://github.com/gbv/jskos. Feedback is appreciated! See https://github.com/gbv/jskos/issues for a list of open issues.

1.2 Conformance requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2.1 URI

An URI is a syntactically correct IRI (RFC 3987).

2.2 URL

An URL is a syntactically correct URL with HTTPS (RECOMMENDED) or HTTP scheme. Note that URLs can contain international characters allowed in IRIs.

2.3 Non-negative integer

A non-negative integer is a JSON number without preceding minus part, without fractional part, or exponent.

2.4 percentage

A percentage is a JSON number with value between zero (0.0 = 0%) and one (1.0 = 100%).

2.5 date

A date is a date or datetime as defined with XML Schema datatype datetime (-?YYYY-MM-DDThh:mm:ss(\.s+)?(Z|[+-]hh:mm)?) date (-?YYYY-MM-DD(Z|[+-]hh:mm)?), gYearMonth (-?YYYY-MM), or gYear (-?YYYY).

2.6 list

A list is a possibly empty array of strings and an optional last member null. Applications MAY ignore or disallow the value null in lists. If null is allowed, lists MUST be interpreted as following to support closed world statements:

• the list [] denotes an empty list.
• the list [null] denotes a non-empty list with unknown members.
• a list [..., null] denotes a list with some known and additional unknown members.
• any other list [...] denotes a list with all members known.

A list MUST NOT contain the empty string except if part of a language map.

2.7 set

A set is a possibly empty array where all members

• are JSON objects of JSKOS resources, except the last member optionally being null,
• and have distinct values in field uri, if this field is given (members MUST not be the same resource).

Member objects SHOULD have a field uri. Applications MAY restrict sets to require the field uri for all non-null members. Applications MAY ignore or disallow the value null in sets. If null is allowed, sets MUST be interpreted as following to support closed world statements:

• the set [] denotes an empty set.
• the set [null] denotes a non-empty set with unknown members.
• a set [..., null] denotes a set with some known and additional unknown members.
• any other set [...] denotes a set with all members known.

2.8 language range

A language range is

• either the character "-"
• or a string that conforms to the syntax of RFC 3066 language tags, limited to lowercase, followed by the character "-",

A language range "x-", where x is a possibly empty string, refers to the set of RFC 3066 language tags that start the string x. For instance language range en- includes language tag en, en-US, and en-GB among others. The language range - refers to all possible language tags.

language-range = [language-tag] "-"
language-tag   = 1*8alpha *("-" 1*8(alpha / DIGIT))
alpha          = %x61-7A  ; a-z

2.9 language map

A language map is a JSON object in which every fields is

• either a RFC 3066 language tag in lowercase that SHOULD also conform to RFC 5646,
• or a language range,

and

• either all values are strings (language map of strings),
• or all values are lists (language map of lists).

and

• string values or list member values mapped to from language tags MUST NOT be the empty string
• string values or list member values mapped to from language ranges MUST BE the empty string

Applications MAY ignore or disallow language ranges in language maps. JSKOS data providers SHOULD make clear whether their data can contain language ranges or not.

If language ranges are allowed, language maps MUST be interpreted as following to support closed world statements:

• Language maps without language range fields indicate that all values are given. In particular the language map {} denotes an empty language map.

• A language range field indicates the existence of additional, unknown values of unknown number.

2.10 location

A location is a JSON object conforming to the GeoJSON specification (RFC 7946) with GeoJSON type being one of Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, or GeometryCollection. Applications MAY restrict the location data type to GeoJSON objects of GeoJSON type Point.

{
  "type": "Point",
  "coordinates": [-49.946944, 41.7325, -3803]
}

2.11 address

An address is a JSON object with any of the following field, each mapped to a string:

2.12 checksum

A checksum is a JSON object with two fields:

The value of SHOULD be specified by a URI from SPDX vocabulary, e.g. http://spdx.org/rdf/terms#checksumAlgorithm_sha256 for SHA-2 with 256 Bit (SHA-256).

2.13 media

A media is a reference to digital content such as images or other audiovisual data. The data model of JSKOS media follows the manifest resource type of IIIF Presentation API 3.0.

A media is a JSON object with at least the following fields:

Additional properties MUST follow the IIIF Presentation API specification. In contrast to IIIF, the fields label and id are not required but RECOMMENDED by JSKOS. JSKOS applications MAY limit the set of supported fields instead of fully implementing all IIIF capabilities.

{
  "type": "Manifest",
  "items": [],
  "thumbnail": [
    {
      "type": "Image",
      "id": "http://example.org/1/thumbnail.jpg",
      "format": "image/jpeg"
    }
  ]
}

3.1 Resource

An resource is a JSON object with the following optional fields:

It is RECOMMENDED to always include the fields uri, type, and @context. The value of field @context SHOULD be https://gbv.github.io/jskos/context.json.

Resources can be tested for sameness based on field uri.

3.2 Item

An item is a resource with the following optional fields (in addition to the optional fields @context, contributor, created, creator, identifier, issued, modified, partOf, publisher, source, type, and uri):

Applications MAY limit the fields notation and/or depiction to lists of a single element or ignore all preceding elements of these lists.

3.3 Concept

A concept is an item and concept bundle with the following optional fields (in addition to the optional fields @context, address, altLabel, changeNote, contributor, created, creator, definition, depiction, editorialNote, endDate, endPlace, example, hiddenLabel, historyNote, identifier, issued, location, modified, notation, note, partOf, place, prefLabel, publisher, scopeNote, source, startDate, startPlace, subjectOf, subject, type, uri, url, memberSet, memberList, memberChoice, and memberRoles):

The first element of field type, if given, MUST be the item type URI http://www.w3.org/2004/02/skos/core#Concept. The type URI http://schema.vocnet.org/NonIndexingConcept should be used as second element for concepts not meant to be used for indexing.

Applications MAY limit the inScheme and/or topConceptOf to sets of a single element or ignore all but one element of these sets.

If both fields broader and ancestors are given, the set broader MUST include the same concept as the first element of ancestors.

The concept bundle fields memberSet, memberList, memberChoice, and memberRoles can be used to express the parts of a composed concept (also known as combined or synthesized concepts) unsorted or sorted. The field memberChoice SHOULD NOT be used without proper documentation because its meaning in this context is unclear. A concept MUST NOT include more than one of concept bundle fields. A concept SHOULD NOT reference itself as part of its concept bundle.

{
  "uri": "http://example.org/terminology/P",
  "type": ["http://www.w3.org/2004/02/skos/core#Concept"],
  "scopeNote": {
    "en": ["state of harmony characterized by lack of violent conflict and freedom from fear of violence"],
    "de": ["Abwesenheit von Gewalt, Angst und anderen Störungen"]
  },
  "prefLabel": {
    "en": "peace",
    "de": "Frieden"
  },
  "altLabel": {
    "de": ["Friede"]
  },
  "notation": ["P"],
  "narrower": [
    {
      "prefLabel": {
        "en": "world peace",
        "de": "Weltfrieden"
      } 
    }
  ],
  "related": [
    { 
      "prefLabel": { "en": "war", "de": "Krieg" } 
    }
  ]
}

{
  "uri": "http://d-nb.info/gnd/7507432-1",
  "prefLabel": { "de": "Drei-Sektoren-Hypothese" },
  "memberSet": [
    { 
      "uri": "http://d-nb.info/gnd/4126823-4",
      "prefLabel": { "de": "Sektoraler Strukturwandel" }
    },
    {
      "uri": "http://d-nb.info/gnd/4161152-4",
      "prefLabel": { "de": "Hypothese" }
    }
  ]
}

{
  "notation": [ "305.40941109033" ],
  "prefLabel": { "en": "Women — Scotland — 18th century" },
  "memberList": [
    {
      "uri": "http://dewey.info/class/305.4/e23/",
      "notation": ["305.4"],
      "prefLabel": { "en": "Women" }
    },
    {
      "uri": "http://dewey.info/class/2--411/e23/",
      "notation": ["T2--411"],
      "prefLabel": { "en": "Scotland" }
    },
    {
      "uri": "http://dewey.info/class/1--09033/e23/",
      "notation": ["T1--09033"],
      "prefLabel": { "en": "18th century, 1700-1799" }
    }
  ]
}

3.4 Concept Schemes

A concept scheme is an item with the following optional fields (in addition to the optional fields @context, address, altLabel, changeNote, contributor, created, creator, definition, depiction, editorialNote, endDate, endPlace, example, hiddenLabel, historyNote, identifier, issued, location, modified, notation, note, partOf, place, prefLabel, publisher, scopeNote, source, startDate, startPlace, subjectOf, subject, type, uri, and url):

The first element of field type, if given, MUST be the item type URI http://www.w3.org/2004/02/skos/core#ConceptScheme.

The values of field uriPattern and notationPattern MUST conform to the regular expression syntax used by XML Schema (Appendix F) and SHOULD be anchored with ^ as first and $ as last character. Applications MAY automatically anchor unanchored regular expressions.

If concepts is a set, all its member concepts SHOULD contain a field inScheme and all MUST contain the same concept scheme in field inScheme if this field is given.

If types and concepts are sets, the types set SHOULD include all concept types for each concept's type other than http://www.w3.org/2004/02/skos/core#Concept.

3.5 Concept Occurrences

An occurrence is a resource and concept bundle with the following optional fields (in addition to the optional fields @context, contributor, created, creator, identifier, issued, modified, partOf, publisher, source, type, uri, memberSet, memberList, memberChoice, and memberRoles):

An occurrence gives the number of a times a concept ("occurrence") or combination of concepts ("co-occurrence") is used in a specific relation to entities from a particular database. For instance the occurrence could give the number of documents indexed with some term in a catalog. The field url typically includes a deep link into the database.

If both count and frequency are given, the total size of the database can derived by multiplication. In this case either both or none of the two fields MUST be zero.

A timestamp, if given, should be stored in field modified.

The actual concept or concepts MAY be given implictly, for instance if the occurrence is part of a concept in field occurrences.

[
  {
    "database": { "uri": "http://uri.gbv.de/database/gvk" },
    "memberSet": [
      {
        "uri": "http://uri.gbv.de/terminology/bk/08.22",
        "prefLabel": { "de": "Mittelalterliche Philosophie" }
      }
    ],
    "count": 3657,
    "modified": "2017-11-22",
    "url": "https://gso.gbv.de/DB=2.1/CMD?ACT=SRCHA&IKT=1016&SRT=YOP&TRM=bkl+08.22"
  },
  {
    "database": { "uri": "http://uri.gbv.de/database/gvk" },
    "memberSet": [
      {
        "uri": "http://dewey.info/class/610/e23/",
        "prefLabel": { "en": "Medicine & health" }
      }
    ],
    "count": 144611,
    "modified": "2017-11-22",
    "url": "https://gso.gbv.de/DB=2.1/CMD?ACT=SRCHA&IKT=1016&SRT=YOP&TRM=ddc+610"
  },
  {
    "database": { "uri": "http://uri.gbv.de/database/gvk" },
    "memberSet": [
      { "uri": "http://uri.gbv.de/terminology/bk/08.22" },
      { "uri": "http://dewey.info/class/610/e23/" }
    ],
    "count": 2,
    "modified": "2017-11-22",
    "url": "https://gso.gbv.de/DB=2.1/CMD?ACT=SRCHA&IKT=1016&SRT=YOP&TRM=bkl+08.22+ddc+610"
  }
]

{
  "type": ["http://www.w3.org/2004/02/skos/core#Concept"],
  "uri": "http://www.wikidata.org/entity/Q5",
  "prefLabel": { "en": "human" },
  "occurrences": [
    {
      "relation": "http://schema.org/about",
      "count": 206,
      "modified": "2017-11-15T14:00:58.796Z"
    },
    {
      "relation": "http://www.wikidata.org/entity/P31",
      "count": 3706347,
      "modified": "2017-11-15T14:00:58.796Z"
    }
  ]
}

3.6 Registries

A registry is an item with the following optional fields (in addition to the optional fields @context, address, altLabel, changeNote, contributor, created, creator, definition, depiction, editorialNote, endDate, endPlace, example, hiddenLabel, historyNote, identifier, issued, location, modified, notation, note, partOf, place, prefLabel, publisher, scopeNote, source, startDate, startPlace, subjectOf, subject, type, uri, and url):

The first element of field type, if given, MUST be the item type URI http://purl.org/cld/cdtype/CatalogueOrIndex.

Registries are collection of concepts, concept schemes, concept types, concept mappings, and/or other registries.

3.7 Distributions

A distribution is an item with the following fields (in addition to the optional fields @context, address, altLabel, changeNote, contributor, created, creator, definition, depiction, editorialNote, endDate, endPlace, example, hiddenLabel, historyNote, identifier, issued, location, modified, notation, note, partOf, place, prefLabel, publisher, scopeNote, source, startDate, startPlace, subjectOf, subject, type, uri, and url):

Distributions mostly cover the class Distribution from Data Catalog Vocabulary.

The format field SHOULD reference a content format rather than its serialization and possible wrapping. The URI of JSKOS is http://format.gbv.de/jskos.

Fields mimetype, compressFormat, and packageFormat SHOULD be IANA media type URIs, if available. Field mimetype MAY be a string for backwards-compatibility.

The first element of field type, if given, MUST be the item type URI http://www.w3.org/ns/dcat#Distribution.

{
  "download": "http://example.org/data/dump.ndjson",
  "mimetype": "application/x-ndjson",
  "format": "http://format.gbv.de/jskos"
}

{
  "prefLabel": { "en": "SKOS in RDF/XML" },
  "download": "http://example.org/data/dump.rdf",
  "mimetype": "application/rdf+xml",
  "format": "http://www.w3.org/2004/02/skos/core"
}

{
  "download": "http://example.org/data/dump.xml.gz",
  "mimetype": "application/xml",
  "format": "http://format.gbv.de/marc/authority",
  "compressFormat": "http://www.iana.org/assignments/media-types/application/gzip"
}

3.8 Concordances

A concordance is an item with the following fields (in addition to the optional fields @context, address, altLabel, changeNote, contributor, created, creator, definition, depiction, editorialNote, endDate, endPlace, example, hiddenLabel, historyNote, identifier, issued, location, modified, notation, note, partOf, prefLabel, publisher, scopeNote, source, startDate, startPlace, subjectOf, subject, type, uri, and url). All fields except fromScheme and toScheme are optional.

The first element of field type, if given, MUST be the item type URI http://rdfs.org/ns/void#Linkset.

Concordances are collections of mappings from one concept scheme to another. If mappings is a set then

• all its members with field fromScheme MUST have the same value like concordance field fromScheme.

• all its members with field toScheme MUST have the same value like concordance field toScheme.

3.9 Concept Mappings

A mapping is an item with the following fields (in addition to the optional fields @context, address, altLabel, changeNote, contributor, created, creator, definition, depiction, editorialNote, endDate, endPlace, example, hiddenLabel, historyNote, identifier, issued, location, modified, notation, note, partOf, prefLabel, publisher, scopeNote, source, startDate, startPlace, subjectOf, subject, type, uri, and url). All fields except from and to are optional.

A mapping represents a mapping between concepts of two concept schemes. It consists two concept bundles with additional metadata not fully defined yet.

The first element of field type, if given, MUST be one of the item types

• http://www.w3.org/2004/02/skos/core#mappingRelation,
• http://www.w3.org/2004/02/skos/core#closeMatch,
• http://www.w3.org/2004/02/skos/core#exactMatch,
• http://www.w3.org/2004/02/skos/core#broadMatch,
• http://www.w3.org/2004/02/skos/core#narrowMatch, and
• http://www.w3.org/2004/02/skos/core#relatedMatch

from SKOS mapping properties. The field type MAY contain additional values but MUST NOT contain multiple of these values.

3.10 Concept Bundles

A concept bundle is a group of concepts. Concept bundles can be used for mappings, composed concepts, and occurrences.

A concept bundle is a JSON object with at most one of the following fields:

Keys of a memberRoles object MUST be URIs and their values MUST be of type set.

{
  "prefLabel": { "en": "knights armor"},
  "memberRoles": {
    "http://example.org/personality": [
      { "prefLabel": { "en": "knight" } }
    ],
    "http://example.org/matter": [
      { "prefLabel": { "en": "workwear" } }
    ],
    "http://example.org/energy": [
      { "prefLabel": { "en": "fight" } }
    ],
    "http://example.org/time": [
      { "prefLabel": { "en": "Middle Ages" } }
    ]
  }
}

3.11 Annotations

An annotation links a JSKOS resource or another annotation with a review, comment or similar document. An annotation is a JSON object that conforms to the Web Annotation Data Model and further contains the following fields as defined:

5.1 Resource sameness

Two resources are same if and only if they both contain field uri with the same value. A resource without field uri is not same to any other resource.

{ "uri": "http://example.org/123", "created": "2007" }
{ "uri": "http://example.org/123", "created": "2015" }

5.2 Closed world statements

By default, a JSKOS document should be interpreted as possibly incomplete: a missing property does not imply that no value exists for this property: this assumption is also known as open-world assumption. Applications SHOULD support closed world statements to explicitly disable the open world assumption for selected properties and explicitly state the known absence or existence of unknown values:

{
  "type": ["http://www.w3.org/2004/02/skos/core#Concept"],
  "prefLabel": { "-": "..." },
  "altLabel": { },
  "notation": [],
  "narrower": [ null ]
}

5.3 Inference rules and integrity constraints

5.4 Extension with custom fields

A JSKOS record MAY contain additional fields for custom usage. These fields MUST start with and underscore (_) or consist of uppercase letters and digits only (A-Z, 0-1). The fields SHOULD be ignored by generic JSKOS applications.

{
  "_id": "e5fa44f2b31c1fb553b6021e7360d07d5d91ff5e",
  "uri": "http://www.wikidata.org/entity/Q34095",
  "prefLabel": { "en": "bronze" },
  "PARTS": ["copper", "tin"]
}