-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathjskos.qmd
1573 lines (1136 loc) · 63.9 KB
/
jskos.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Introduction
**JSKOS** (**JS**ON for **K**nowledge **O**rganization **S**ystems) defines
a JavaScript Object Notation (JSON) structure to encode knowledge organization
systems (KOS) and semantic artifacts, such as classifications, thesauri,
authority files, and knowledge graphs.
The core of JSKOS is an encoding of Simple Knowledge Organisation System
(SKOS), an application of the Resource Description Framework (RDF), in
JavaScript Object Notation for Linked Data (JSON-LD). JSKOS is compatible with
these technologies but it does notrequire to be experienced with more than
plain JSON ([RFC 8259]). Another influence of JSKOS is the data model of
Wikibase, which can partly be encoded in JSKOS as well.
## Outline
In addition to [concepts] and [concept schemes] JSKOS can express information about:
- [mappings] and [concordances] for alignments between concepts
- [occurrences] of concepts in databases
- [registries] and [distributions] to package and provide data
- general [resources] (any kind of entities)
- [annotations] to review and comment on resources
- qualified information with [qualified statements]
- incomplete and deprecated information via [ranks](#rank) and [closed world statements]
See [object types] for the class hierarchy of JSKOS data elements.
## Status of this document
JSKOS is being specified since 2014 based on actual use cases and without a
committee (see [changelog]). The 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.
## 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].
Only @sec-data-types to @sec-additional-rules of this document and its
[normative references] are normative. Examples and notes (such as the following)
are neither part of conformance requirements.
::: {.callout-note}
The appendix includes information how to [validate against this specification](#validation),
for instance with JSON Schema, but these methods do not fully cover all aspects of JSKOS.
:::
# Data types {#sec-data-types}
[string]: #data-types
[boolean]: #data-types
JSKOS is based on JSON which consists of *objects* with pairs of *fields* and
*values*, *arrays* with *members*, *strings*, *numbers*, and the special values
`true`, `false`, and `null`. All strings and fields of a JSKOS document MUST
be normalized to Unicode Normalization Form C (NFC). Applications processing
JSON MAY accept JSON documents not normalized in NFC by performing NFC
normalization.
JSKOS further restricts JSON with reference to the following data types:
## URI
An **URI** is a syntactically correct IRI ([RFC 3987]).
## URL
An **URL** is a syntactically correct URL with scheme `https` (RECOMMENDED) or `http` ([RFC 3986]).
## non-negative integer
A **non-negative integer** is a JSON number without preceding minus part, fractional part, and exponent.
## percentage
A **percentage** is a JSON number with value between zero (`0.0` = 0%) and one (`1.0` = 100%).
## date
A **date** is a date or date and time as defined with XML Schema datatype
[datetime](https://www.w3.org/TR/xmlschema-2/#dateTime)
(`-?YYYY-MM-DDThh:mm:ss(\.s+)?(Z|[+-]hh:mm)?`)
[date](https://www.w3.org/TR/xmlschema-2/#date) (`-?YYYY-MM-DD(Z|[+-]hh:mm)?`),
[gYearMonth](https://www.w3.org/TR/xmlschema-2/#gYearMonth) (`-?YYYY-MM`),
or [gYear](https://www.w3.org/TR/xmlschema-2/#gYear) (`-?YYYY`).
## extended date
An **extended date** is a date, date and time, or interval in [Extended Date/Time Format (EDTF)](https://www.loc.gov/standards/datetime/) Level 1.
::: {.callout-note}
An extended date includes, in adition to [date]:
- Intervals of dates (e.g. `1949-10/1990-10`, or `2021/..`)
- Seasons (e.g. `2001-21`)
- Years with more then four digits (e.g. `Y-50000`)
- Qualifiers for uncertain (`?`), approximate (`~`) or both (`%`)
- Unspecified digits marked with `X`
:::
## language tag
A **language tag** is a non-empty string that conforms to the syntax of [RFC 3066] language tags, limited to lowercase.
## list
[lists]: #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].
## set
A **set** is a possibly empty array where all members
* are JSON objects of JSKOS [resources], except the last member optionally being `null`,
* have distinct values in field `uri`, if this field is given
(members MUST NOT be the [same resource]),
* and have at most one member with field [`rank`](#rank) being the string `preferred`.
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.
:::{#lst-ex-sets}
The following JSON values are JSKOS sets:
* `[]`{.json}
* `[null]`{.json}
* `[{"uri":"http://example.org/123"}]`{.json}
* `[{"uri":"http://example.org/123"},null]`{.json}
* `[{"uri":"http://example.org/123"},{"uri":"http://example.org/456"}]`{.json}
* `[{"uri":"http://example.org/123"},{"notation":["xyz"]}]`{.json}
The following JSON values are not valid JSKOS sets:
* `[null,{"uri":"http://example.org/123"}]`{.json}\
(`null` only allowed as last member)
* `[{"uri":"http://example.org/123"},{"uri":"http://example.org/123"}]`{.json}\
(field `uri` must be unique)
:::
::: {.callout-note}
It is not defined yet whether and when the order of elements is relevant or not.
:::
## rank
A **rank** is one of the strings `preferred`, `normal`, and `deprecated`.
Applications MAY ignore or limit ranks to selected use cases.
Elements of a [set] and [qualified values] are expected to have a field `rank`
with a rank value. If an element lacks a rank, its default rank is `normal`.
The rank `deprecated` is used for elements that are known to include errors.
Applications MAY filter out these elements.
The rank `preferred` is used to allow selection of one most relevant element
from its array. Applications MAY reduce arrays of multiple elements to an array
with the single element of rank `preferred`.
::: {.callout-note}
Wikibase data model includes ranks with same semantics, see
[ranks in Wikidata](https://www.wikidata.org/wiki/Help:Ranking) for background.
:::
::: {#lst-ranks lst-cap="A resource with ranked publishers"}
~~~json
{
"publisher": [
{ "prefLabel": { "en": "Acme Corporation" }, "rank": "preferred" },
{ "prefLabel": { "en": "DIY Products" }, "rank": "normal" }
]
}
~~~
:::
## language range
A **language range** is
* either the character "`-`"
* or a [language tag], 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.
A language range MUST conform to the following ABNF grammar ([RFC 5234]):
```abnf
language-range = [language-tag] "-"
language-tag = 1*8alpha *("-" 1*8(alpha / DIGIT))
alpha = %x61-7A ; a-z
```
JSKOS language ranges can be mapped to and from basic language ranges as
defined in [RFC 4647]. The main difference of JSKOS language ranges is they can
be distinguished from [RFC 3066] based on their string value (always ending
with "`-`"). For instance "`en`" could be an [RFC 3066] language tag or a
[RFC 4647] language range but in JSKOS it is always a language tag only:
JSKOS RFC 3066 RFC 4647
--------------------------------------- ----- -------- --------
language tag for English `en` `en`
languag range for all English variants `en-` `en`
## language map
A **language map** is a JSON object in which every fields is
* either a [language tag] 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.
::: {#lst-language-maps}
The following language maps make use of language ranges and placeholders:
* ` {"-":""}`, ` {"-":""}`, ` {"-":[]}`, and ` {"-":[""]}`
all denote non-empty language maps with unknown language tags and values.
* ` {"en":"bird","-":""}` denotes a language map with an English value
and additional values in other language tags.
* ` {"en":"bird"}` denotes a language map with an English value only.
* ` {"en-":""}` denotes a language map that only
contains values with language tags starting with `en`.
:::
::: {.callout-note}
JSON-LD disallows language map fields ending with `"-"` so all fields that are
language ranges MUST be removed before reading [JSKOS as JSON-LD].
:::
::: {.callout-note}
The language tag `und` can be used to include strings of unknown or unspecified language.
:::
## checksum
A **checksum** is a JSON object with two fields:
field type description
----------- ------- -----------
algorithm [URI] checksum algorithm
value string lower case hexidecimal encoded digest value
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).
## location
[location]: #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`.
::: {#lst-titanic lst-cap="Position of the RMS Titanic as point"}
~~~json
{
"type": "Point",
"coordinates": [-49.946944, 41.7325, -3803]
}
~~~
:::
## address
An **address** is a JSON object with any of the following fields, each mapped to a string.
::: {.callout-note}
The adress format is based on vCard ADR value components of same name ([RFC 6350, section 6.3.1](https://www.rfc-editor.org/rfc/rfc6350.html#section-6.3.1)) and on schema.org type [PostalAddress](https://schema.org/PostalAddress) but both of these standards are non-normative.
:::
field description schema.org property
-------- ---------------------------------------------------------- ------------------------------------------------------------
pobox the post office box [postOfficeBoxNumber](http://schema.org/postOfficeBoxNumber)
ext the extended address (e.g., apartment or suite number) [streetAddress](http://schema.org/streetAddress)
street the street address [streetAddress](http://schema.org/streetAddress)
locality the locality (e.g., city) [addressLocality](http://schema.org/addressLocality)
region the region (e.g., state or province) [addressRegion](http://schema.org/addressRegion)
code the postal code [postalCode](http://schema.org/postalCode)
country the country name [addressCountry](http://schema.org/addressCountry)
## 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](https://iiif.io/api/presentation/3.0/).
A **media** is a JSON object with at least the following fields:
field type description
------- ------- ---------------------------
type string the value "Manifest"
items array list of IIIF Canvas objects
Additional fields 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.
::: {#lst-thubnail lst-cap="Thumbnail image specified as media"}
~~~json
{
"type": "Manifest",
"items": [],
"thumbnail": [
{
"type": "Image",
"id": "http://example.org/1/thumbnail.jpg",
"format": "image/jpeg"
}
]
}
~~~
:::
# Resource and property types
[resource type]: #resource-and-property-types
[resource types]: #resource-and-property-types
[property type]: #resource-and-property-types
[property types]: #resource-and-property-types
[item type]: #item-types
Resource types and property types are [concepts] with MANDATORY field `uri`.
Both can be referred to implicitly ba referencing their [URI] and they can be
expressed explicitly, for instance in a [registry].
::: {.callout-note}
Ressource types and property types roughly map to RDF classes and RDF properties
but JSKOS does not require or imply the RDF data model.
:::
A **resource type** is a [concept] used to distinguish different kinds of
concepts or other [resources]. Concept types are referred to by their [URI] in
array field `type` of a [resource].
An **item type** is a resource type with one of the following [URI]s. Item
types are used to identify the different kinds of JSKOS [items](#item)
(see [object types]) and types of [mappings]:
item item type
------------------- -----------------------------------------------------
[concept] <http://www.w3.org/2004/02/skos/core#Concept>
[concept scheme] <http://www.w3.org/2004/02/skos/core#ConceptScheme>
[registry] <http://purl.org/cld/cdtype/CatalogueOrIndex>
[distribution] <http://www.w3.org/ns/dcat#Distribution>
[concordance] <http://rdfs.org/ns/void#Linkset>
[mapping] <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>
<http://www.w3.org/2004/02/skos/core#relatedMatch>
------------------- -----------------------------------------------------
::: {.callout-note}
See appendix [item types as concepts] for a partial explicit encoding of item types.
:::
A **property type** is a [concept] used to specify the type of a [qualified
statement]. Property types are referenced by their [URI] in the keys of
a [qualified map].
# Object types
JSKOS defines the following types of JSON objects:
- [resources] for all kinds of entities
- [items] for named entities
- [concepts] for entities from a knowledge organization system
- [concept schemes] for compiled collections of concepts (knowledge organization systems)
- [mappings] for mappings between concepts of two concept schemes
- [concordances] for curated collections of mappings
- [registries] for collections of items (concepts, concept schemes...)
- [distributions] for available forms to access the content of an item
- [occurrences] for counts of concept uses
- [annotations] to review and comment on individual resources
Object types [concept], [mapping], and [occurrence] are also [concept bundles].
## Resource
[resource]: #resource
[resources]: #resource
An **resource** is a JSON object with the following optional fields:
field type description
------------------- ---------------------------------------- ------------------------------------------------------------------
@context [URI] or list of URI reference to a JSON-LD context document (see [appendix](#json-ld))
uri [URI] primary globally unique identifier
identifier [list] additional identifiers
type [list] of [URI] URIs of types
created [date] date of creation of the resource
issued [date] date of publication of the resource
modified [date] date of last modification of the resource
creator [set] agent primarily responsible for creation of the resource
contributor [set] agent responsible for making contributions to the resource
source [set] sources from which the described resource is derived
publisher [set] agent responsible for making the resource available
partOf [set] [resources] which this resource is part of (if no other field applies)
qualifiedRelations [qualified map] of [qualified relation] qualified relations to other resources
qualifiedDates [qualified map] of [qualified date] qualified dates (related events or periods)
qualifiedLiterals [qualified map] of [qualified literal] qualified literals
rank [rank] a [rank] (only relevant if the resource is part of a [set])
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](#resource-sameness) based on field `uri`.
The fields `created`, `issued`, `modified`, `creator`, `contributor`, `source`,
and `publisher` do not refer to the entity referenced by the resource but to
the resource object. For instance a resource about the city of Rome might have
a recent date `created` while the founding date `-0753` would be stated in
[item] field `startDate`.
For use cases of field `partOf` see also [Concept Schemes].
## Item
[item]: #item
[items]: #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`, `rank`, `source`,
`type`, and `uri`):
field type description
------------- ------------------------- ----------------------------------------------
url [URL] URL of a page with information about the item
notation [list] list of notations
prefLabel [language map] of strings preferred labels, indexed by language
altLabel [language map] of [list] alternative labels, indexed by language
hiddenLabel [language map] of [list] hidden labels, indexed by language
scopeNote [language map] of [list] see [SKOS Documentary Notes]
definition [language map] of [list] see [SKOS Documentary Notes]
example [language map] of [list] see [SKOS Documentary Notes]
historyNote [language map] of [list] see [SKOS Documentary Notes]
editorialNote [language map] of [list] see [SKOS Documentary Notes]
changeNote [language map] of [list] see [SKOS Documentary Notes]
note [language map] of [list] see [SKOS Documentary Notes]
startDate [extended date] date of begin (birth, creation...) of the item
endDate [extended date] date of end (death, resolution...) of the item
relatedDate [extended date] other date somehow related to the item (deprecated)
relatedDates array of [extended date] other dates somehow related to the item
startPlace [set] where an item started (e.g. place of birth)
endPlace [set] where an item ended (e.g. place of death)
place [set] other relevant place(s) of the item
location [location] geographic location of the item
address [address] postal address of the item
replacedBy [set] of [item] related items that supplant, displace, or supersede this item
basedOn [set] of [item] related items that inspired or led to this item
subject [set] what this item is about (e.g. topic)
subjectOf [set] resources about this item (e.g. documentation)
depiction [list] of [URL] list of image URLs depicting the item
media [list] of [media] audiovisual or other digital content representing the item
The first element of array `type`, if given, MUST be an [item type] URI.
Applications MAY limit the fields `notation` and/or `depiction` to lists of a single
element or ignore all preceding elements of these lists.
If `startDate` is given, the value of `endDate` MUST NOT be an interval with open start.
If `endDate` is given, the value of `startDate` MUST NOT be an interval with open end.
To state one primary date of an item set `startDate` and `endDate` to the same value.
## Concept
[concept]: #concept
[concepts]: #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`, `rank`, `scopeNote`,
`source`, `startDate`, `startPlace`, `subjectOf`, `subject`, `type`, `uri`,
`url`, `memberSet`, `memberList`, `memberChoice`, and `memberRoles`):
field type description
------------ -------------------------- -------------------------------------------------------------------------------
narrower [set] narrower concepts
broader [set] broader concepts
related [set] generally related concepts
previous [set] related concepts ordered somehow before the concept
next [set] related concepts ordered somehow after the concept
ancestors [set] list of ancestors, possibly up to a top concept
inScheme [set] of [concept schemes] concept schemes the concept belongs to
topConceptOf [set] of [concept schemes] concept schemes the concept is a top concept of
mappings [set] of [mappings] mappings from and/or to this concept
occurrences [set] of [occurrences] occurrences with this concept
deprecated [boolean] mark a concept as deprecated (false by default)
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.
::: {.callout-note}
The "ancestors" field is useful in particular for monohierarchical classifications
but it's not forbidden to choose just one arbitrary path of concepts that are
connected by the broader relation.
:::
```{.json #lst-concept1 lst-cap="concept"}
{{< include examples/example.concept.json >}}
```
```{.json #lst-concept2 lst-cap="concept from GND"}
{{< include examples/gnd-7507432-1.concept.json >}}
```
```{.json #lst-concept3 lst-cap="concept from DDC"}
{{< include examples/ddc-305.40941109033.concept.json >}}
```
## Concept Schemes
[concept scheme]: #concept-schemes
[concept schemes]: #concept-schemes
[scheme]: #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`, `rank`, `scopeNote`,
`source`, `startDate`, `startPlace`, `subjectOf`, `subject`, `type`, `uri`, and
`url`):
field type definition
---------------- -------------------------- --------------------------------------------------------------------------------------
topConcepts [set] of [concepts] top [concepts] of the scheme
versionOf [set] of [concept schemes] [concept scheme] which this scheme is a version or edition of
namespace [URI] URI namespace that all concepts URIs are expected to start with
uriPattern string regular expression that all concept URIs are expected to match
notationPattern string regular expression that all primary notations should follow
notationExamples [list] of string list of some valid notations as examples
concepts [set] of [concepts] concepts in the scheme
types [set] of [concepts] [resource type] URIs of concepts in this scheme
distributions [set] of [distributions] [Distributions] to access the content of the concept scheme
extent string Size of the concept scheme
languages [list] of language tags Supported languages
license [set] Licenses which the full scheme can be used under
The first element of array 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](https://www.w3.org/TR/xmlschema-2/#regexs))
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 [resource type] URIs
for each concept's `type` other than `http://www.w3.org/2004/02/skos/core#Concept`.
Resource field `partOf` at a concept scheme MUST be interpreted as following:
- if the linked resource is another [concept scheme], the concept scheme is *subset of* the other concept scheme
- if the linked resource is a [registry], the concept scheme is *listed in* in the registry
Item field `replacedBy` at a concept schemes SHOULD be used to connect successive editions or concept scheme that have been replaced or renamed.
Item field `basedOn` at a concept schemes SHOULD be used to connect translations, abridged versions, or concept schemes that have been inspired by another concept scheme.
## Concept Occurrences
[occurrences]: #concept-occurrences
[occurrence]: #concept-occurrences
[concept occurrence]: #concept-occurrence
[concept occurrences]: #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`):
field type definition
------------ ---------------------- ----------------------------------------------
count [non-negative integer] number of times the concepts are used
database [item] database in which the concepts are used
frequency [percentage] count divided by total number of possible uses
relation [URI] type of relation between concepts and entities
url [URL] URL of a page with information about the occurrence
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`.
<!-- TODO: specify explicit inference rules for implicitly given concepts? -->
:::{#lst-ex2}
Two occurrences and their combined co-occurrence from GBV Union Catalogue (GVK) as of November 22th, 2017: [3657 records](https://gso.gbv.de/DB=2.1/CMD?ACT=SRCHA&IKT=1016&SRT=YOP&TRM=bkl+08.22) are indexed with class `08.22` (medieval philosophy) from Basisklassifikation, [144611](https://gso.gbv.de/DB=2.1/CMD?ACT=SRCHA&IKT=1016&SRT=YOP&TRM=ddc+610) with DDC notation `610` (Medicine & health) and [2 records](https://gso.gbv.de/DB=2.1/CMD?ACT=SRCHA&IKT=1016&SRT=YOP&TRM=bkl+08.22+ddc+610) with both.
```{.json}
{{< include examples/gvk-co.occurrence.json >}}
```
:::
:::{#lst-ex-wikidata}
The Wikidata [concept of an individual human](http://www.wikidata.org/entity/Q5) is linked to 206 Wikimedia sites (mostly Wikipedia language editions) and more than 3.7 million people (instances of <http://www.wikidata.org/entity/P31>) at November 15th, 2017.
```{.json}
{{< include examples/wikidata-occurrences.concept.json >}}
```
:::
## Registries
[registries]: #registries
[registry]: #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`, `rank`, `scopeNote`,
`source`, `startDate`, `startPlace`, `subjectOf`, `subject`, `type`, `uri`, and
`url`):
field type definition
------------ -------------------------- --------------------------------------------------------------------------------------
concepts [set] of [concepts] [concepts] in this registry
schemes [set] of [concept schemes] [concept schemes] in this registry
types [set] of [concepts] [resource types] in this registry
properties [set] of [concepts] [property types] in this registry
mappings [set] of [mappings] [mappings] in this registry
registries [set] of [registries] other registries in this registry
concordances [set] of [concordances] [concordances] in this registry
occurrences [set] of [occurrences] [occurrences] in this registry
extent string Size of the registry
languages [list] Supported languages
license [set] Licenses which the full registry content can be used under
The first element of array field `type`, if given, MUST be the [item type] URI
<http://purl.org/cld/cdtype/CatalogueOrIndex>.
Registries are collection of [concepts], [concept schemes], [resource types],
[property types], [concept mappings], and/or other registries.
::: {.callout-note}
Registries are the top JSKOS entity, followed by
[concordances], [mappings] [concept schemes], and on the lowest level
[concepts] and [resource types]. See [Distributions] for an alternative.
Additional integrity rules for registries will be defined (TODO).
:::
## Distributions
[distribution]: #distributions
[distributions]: #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`, `rank`, `scopeNote`, `source`, `startDate`, `startPlace`,
`subjectOf`, `subject`, `type`, `uri`, and `url`):
Distributions mostly cover the [class Distribution](https://www.w3.org/TR/vocab-dcat-3/#Class:Distribution) from [Data Catalog Vocabulary](https://www.w3.org/TR/vocab-dcat-3/).
field type definition
-------------- --------------- ------------------------------------------------------------------
download [URL] location of a file with distribution content in given format
accessURL [URL] URL of an API or landing page to retrieve the distribution content
format [URI] data format identifier of the distribution content
mimetype [URI] or string Internet Media Type (also known as MIME type)
compressFormat [URI] compression format of the distribution
packageFormat [URI] packaging format when multiple files are grouped together
license [set] license which the data can be used under
size string Size of a distribution in bytes or literal such as "1.5 MB"
checksum [checksum] Checksum of the download (algorithm and digest value)
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 array field `type`, if given, MUST be the [item type] URI
<http://www.w3.org/ns/dcat#Distribution>.
::: {.callout-note}
Access to [concept schemes] and [concordances] can also be specified with
fields `concepts`, `types`, and `mappings`, respectively. Distributions provide
an alternative and extensible method to express access methods.
:::
::: {#lst-ex}
Distribution of a newline-delimited JSKOS file:
```{.json}
{{< include examples/jskos.distribution.json >}}
```
Distribution of a RDF/XML with SKOS data:
```{.json}
{{< include examples/rdfxml.distribution.json >}}
```
Distribution of a gzip-compressed MARC/XML file in [MARC 21 Format for
Authority Data](https://www.loc.gov/marc/authority/):
```{.json}
{{< include examples/marc.distribution.json >}}
```
:::
## Concordances
[concordances]: #concordances
[concordance]: #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`,
`rank`, `scopeNote`, `source`, `startDate`, `startPlace`, `subjectOf`,
`subject`, `type`, `uri`, and `url`). All fields except `fromScheme` and
`toScheme` are optional.
field type definition
------------- ------------------------- ------------------------------------------------------
mappings [set] of [mappings] [mappings] in this concordance
distributions [set] of [distributions] [distributions] to access the concordance
fromScheme [concept scheme] Source concept scheme
toScheme [concept scheme] Target concept scheme
extent string Size of the concordance
license [set] License which the full concordance can be used under
The first element of array 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`.
::: {.callout-note}
There is an additional integrity constraint refering to field `inScheme` if concepts in mappings in concordances.
:::
## Concept Mappings
[mappings]: #concept-mappings
[mapping]: #concept-mappings
[concept mapping]: #concept-mappings
[concept mappings]: #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`,
`rank`, `scopeNote`, `source`, `startDate`, `startPlace`, `subjectOf`,
`subject`, `type`, `uri`, and `url`). All fields except `from` and `to` are
optional.
field type definition
---------------- ---------------- ----------------------------------------------
from [concept bundle] concepts mapped from
to [concept bundle] concepts mapped to
fromScheme [concept scheme] source concept scheme
toScheme [concept scheme] target concept scheme
mappingRelevance number numerical confidence value between 0 and 1
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 array field `type`, if given, MUST be an [item type] for
mappings from the [SKOS mapping properties](http://www.w3.org/TR/skos-reference/#mapping).
The field `type` MAY contain additional values but MUST NOT contain multiple of these values.
::: {.callout-note}
When mappings are dynamically created it can be useful to assign a non-HTTP URI
such as `urn:uuid:687b973c-38ab-48fb-b4ea-2b77abf557b7`.
:::
::: {.callout-note}
Applications MAY use concept mappings to derive simple statements with [SKOS Mapping Properties](https://www.w3.org/TR/skos-reference/#mapping)
but SKOS integrity rules for mappings do not apply automatically.
:::
## Concept Bundles
[concept bundles]: #concept-bundles
[concept bundle]: #concept-bundles
[collections]: #concept-bundles
[concept collections]: #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:
field type definition
----------- --------------------------- ----------------------------------------------------------------------
memberSet [set] of [concepts] [concepts] in this bundle (unordered)
memberList ordered [set] of [concepts] [concepts] in this bundle (ordered)
memberChoice [set] of [concepts] [concepts] in this bundle to choose from
memberRoles object Object mapping role URIs to [set]s of [concepts]
Keys of a `memberRoles` object MUST be URIs and their values MUST be of type [set].
```{.json #lst-member-roles lst-cap="..."}
{{< include examples/memberRoles.concept.json >}}
```
::: {.callout-note}
* Concept bundles could also be used for
[SKOS concept collections](http://www.w3.org/TR/skos-reference/#collections),
see <https://github.com/gbv/jskos/issues/7> for discussion.
* Concepts from a bundle may also come from different concept schemes!
* A concept bundle may be empty, for instance to indicate that no appropriate
concepts exists for a given concept scheme:
```json
{
...
"to": { "memberSet": [] },
"toScheme": {"uri": "http://dewey.info/scheme/ddc/"}
}
```
Normalization rules may be added to prefer one kind of expressing an empty concept bundle.
:::
## Annotations
[annotation]: #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:
field type definition
----------- --------------------------------- ----------------------------------------------
@context [URL] the value `http://www.w3.org/ns/anno.jsonld`
type string the value `Annotation`
id [URI] globally unique identifier of the annotation
target [URI], [Resource] or [Annotation] object being annotated, or its URI
[Web Annotation Data Model]: https://www.w3.org/TR/annotation-model/
# Qualified statements
[qualified map]: #qualified-statements
[qualified statement]: #qualified-statements
JSKOS defines a set of common fields (such as `prefLabel`, `startDate`, `place`, and `media`) to facilitate interoperability across diverse knowledge organization systems. Application of these fields comes with simplification and lack of context information. To allow for more details, qualified statements can express typed and qualified data at cost of interoperability.
::: {.callout-note}
Qualified statements are similar but not identical to properties in a property graph and to referenced statements in Wikibase data model.
:::
The term **qualified statement** refers to the combination of a [property type] and a [qualified value]. Qualified statements are grouped in *qualified maps* by the data type of their qualified values.
A **qualified map** is a JSON object that maps [property types] to [qualified values].
``` {.json #lst-qualified-map lst-cap="Qualified map with property types from schema.org"}
{
"https://schema.org/award": [ ... ],
"https://schema.org/performerIn": [ ... ]
}
```
## Qualified value
[qualified values]: #qualified-value
A **qualified value** is a JSON object with the following optional fields:
field type definition
----------- --------------- --------------------------------------------
startDate [extended date] date when the statement started to be valid
endDate [extended date] date when the statementn ended to be valid
source [set] sources as evidence for the statement
rank [rank] [rank] of the statement
If field `startDate` is given in a qualified value, the value of field `endDate` MUST NOT be an interval with open start.
If field `endDate` is given in a qualified value, the value of `startDate` MUST NOT be an interval with open end.
To state one primary date of a qualified value, set `startDate` and `endDate` to the same value.
In addition there are fields depending on the data type of the qualified value. These data types are:
- [Qualified relation] for links between resources
- [Qualified date] to reference related events and periods
- [Qualified literal] to reference names and labels
## Qualified relation
[qualified relations]: #qualified-relations