README.md 4.6 KB
Newer Older
1
# Community OSDU Schema Repository 
2

3
4
This repository keeps a copy of the Data Definitions schema definitions. The original source is located 
[here](https://gitlab.opengroup.org/osdu/subcommittees/data-def/work-products/schema/-/tree/master/).
5

6
The repository contains
7

8
# 1. Consumption Areas
9

10
## 1.1. Schemas
11

12
13
14
15
16
17
18
19
The folder [SchemaRegistrationResources/shared-schemas](SchemaRegistrationResources/shared-schemas)
contains JSON payloads to register the OSDU schemas with the 
[Schema service](https://community.opengroup.org/osdu/platform/system/schema-service/-/blob/master/docs/api/schema.yaml) 
(a system service).
The same resources are also located with the Schema service 
[bootstrapping folder](https://community.opengroup.org/osdu/platform/system/schema-service/-/tree/master/deployments/shared-schemas)
in the system service. The resources are bootstrapped when the 
Schema service is re-deployed.
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
If the schemas are to be registered independent of the Schema service 
deployment then the script 
[DeploySharedSchemas.py](https://community.opengroup.org/osdu/platform/system/schema-service/-/blob/master/deployments/scripts/DeploySharedSchemas.py)
can help to perform this - with the respective environment settings of 
course.

## 1.2 Reference Values

Many schema properties are reference-value controlled, i.e. a
string property holds the `id` to a reference value catalog 
(all records belonging to the same `osdu:wks:reference-data--SomeCatalog:1.0.0`
`kind`).

The [table of contents](ReferenceValues/Manifests/README.md) 
provides an alphabetic list of catalogs under the
[ReferenceValues](ReferenceValues) folder. Reference 
value types fall in one of three categories:
1. `FIXED` - The list of reference values cannot be extended or changed, except 
   by the governing authority/authorities itself.
1. `OPEN` - An initial list of reference values is delivered by OSDU; values provided 
   by OSDU cannot be changed, but the list of reference values can be extended by the 
   operators.
1. `LOCAL` - An initial list of reference values *may* by delivered by OSDU; values can 
   be changed, the list of values can be extended or entirely replaced by the 
   operators.

The governance mode is listed in the
[table of contents](ReferenceValues/Manifests/README.md) with links 
to the manifests and original workbooks (easier to read for humans).

# 2. Schema Documentation

The list of all known schema kinds  and schema fragments can be found in this 
[README](./E-R/README.md).
55
The entities are hyperlinked individual markdown documentations and E-R diagrams.
56

57
58
59
60
A list of supported formats (expressing the desire to be supported) is given in the
[work-product-component folder](E-R/work-product-component/README.md).

# 3. Example Records
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

Auto-generated examples are provided in the [Examples](./Examples) 
folder structure (same organization as the consumption area). Examples
use defined reference values where available or use artificial names.
Relationships use fantasy record `id`s, which match the relationship pattern.
The examples are validated against the schemas, however, due to 
the open definition (default `"additional-properties": true`) and 
sparse usage of `required` properties, the validation is very 
tolerant.

The examples populate every defined schema property. Special cases:
* `array` properties are only populated with a single element unless 
  a minimum number of elements is required.
* `oneOf` schema constructs select the second option.

76
77
78
79
80
81
82
83
84
85
86
87
88
The [Documentation pages](E-R/README.md) provide links to each individual
example record per type in the header section. 

# 4. Supporting Folders

## 4.1 Generated

[Generated](./Generated) contains the final schemas. Note that
all the schemas use _**relative**_ file references in `$ref` expressions,
which have to be replaced by schema id (=kind) references. 
This representation is useful as some integrated development environments
support live checking of local references and even refactoring. The 
schemas in [Generated](./Generated) cannot be registered with the
89
Schema service. **The resources for schema registration are provided here:**
90
91
92
93
94
95
96
97
[SchemaRegistrationResources/shared-schemas](SchemaRegistrationResources/shared-schemas).


## 4.2. Authoring
This folder is less relevant for consumers but referenced from the documentation -
these are the essential source for the script [Generated](./Generated) schemas. 
Those schema representations provide an 'uncluttered' view on the
essential contents because standard components, like the boilerplate 
98
99
100
101
102
103
system properties are suppressed.

# 5. Change Log

The changes compared to the respective DD mirror snapshots are accumulated in the 
[ChangeLog.md](./ChangeLog.md).