Skip to content

Commit 56fd539

Browse files
clementbironclementbiron
authored
Proposal for Schema Improvements (#85)
2 parents 721b740 + 5aa9c28 commit 56fd539

2 files changed

Lines changed: 315 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
All changes that impact users of this module are documented in this file, in the [Common Changelog](https://common-changelog.org) format with some additional specifications defined in the [CONTRIBUTING](./CONTRIBUTING.md) file. This codebase adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
44

5+
## Unreleased [no-release]
6+
7+
_Modifications made in this changeset do not add, remove or alter any behavior, dependency, API or functionality of the software. They only change non-functional parts of the repository, such as the README file or CI workflows._
8+
59
## 1.4.0 - 2024-10-24
610

711
_Full changeset and discussions: [#86](https://github.com/OpenTermsArchive/terms-types/pull/86)._

‎decision-records/0001-schema-improvements.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
# Proposal for Schema Improvements
2+
3+
- Date: 2024-10-22
4+
5+
## Introduction
6+
7+
This RFC proposes improvements to the current data schema to improve usability. Since changing the data structure entails publishing a new major version, which is costly for downstream dependencies, it is relevant to consider the entire vocabulary and structure to avoid later changes in the near future.
8+
9+
## Context and Problem Statement
10+
11+
### Confusion around the `writer` field
12+
13+
The `writer` field is filled in with `service provider` in 32 out of 41 existing terms types, which does not add much value. Other values, such as `transportation operator (airline, railway, bus…)` (once), `paid-for goods or service provider` (once), `online marketplace` (twice), `search engine or intermediation service provider` (twice), and `intermediation service provider` (three times), only provide information about the industry in which the service operates, which is not the original purpose of the `writer` field.
14+
15+
### Ambiguity in the `audience` field
16+
17+
There is ambiguity between the audience of the document and the audience of the service. Currently, the `audience` field could be interpreted in these two ways.
18+
19+
## Proposed solutions
20+
21+
In any case, this file format does not have default values. Optimizations to remove redundancy do not bring much in the context, and add ambiguity instead.
22+
23+
### Solution A
24+
25+
- Remove `commitment` object
26+
- Update `object` to `defines` field
27+
- Update `writer` to `used by` field
28+
- Update `audience` to `addressed to` field
29+
- Update `references` to `described in` field
30+
31+
#### Schema
32+
33+
```json
34+
"<terms type name>": {
35+
"defines": "...",
36+
"used by": "...",
37+
"addressed to": "...",
38+
"also known as": [ // Optional array of strings
39+
"..."
40+
],
41+
"described in": { // Optional object with name/url pairs
42+
"name": "url"
43+
}
44+
}
45+
```
46+
47+
##### Examples
48+
49+
```json
50+
"Editorial Policy": {
51+
"defines": "the writing and publishing standards and principles",
52+
"used by": "service provider",
53+
"addressed to": "end user",
54+
"also known as": [
55+
"Editorial Guidelines"
56+
],
57+
"described in": {
58+
"Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/35"
59+
}
60+
}
61+
```
62+
63+
```json
64+
"Conditions of Carriage": {
65+
"defines": "benefits and limitations associated with the transportation being provided",
66+
"used by": "transportation operator (airline, railway, bus…)",
67+
"addressed to": "passenger",
68+
"also known as": [
69+
"Transport Conditions"
70+
]
71+
}
72+
```
73+
74+
### Solution B
75+
76+
- Remove `commitment` object
77+
- Remove `writer` field
78+
- Update `object` to `topic` field
79+
- Update `audience` to `target` field
80+
- Update `also known as` to `aliases` field
81+
82+
#### Schema
83+
84+
```json
85+
"<terms type name>": {
86+
"topic": "...",
87+
"target": "...",
88+
"aliases": [ // Optional array of strings
89+
"..."
90+
],
91+
"references": { // Optional object with name/url pairs
92+
"name": "url"
93+
}
94+
}
95+
```
96+
97+
##### Examples
98+
99+
```json
100+
"Editorial Policy": {
101+
"topic": "the writing and publishing standards and principles",
102+
"target": "end user",
103+
"aliases": [
104+
"Editorial Guidelines"
105+
],
106+
"references": {
107+
"Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/35"
108+
}
109+
}
110+
```
111+
112+
```json
113+
"Conditions of Carriage": {
114+
"topic": "benefits and limitations associated with the transportation being provided",
115+
"target": "passenger",
116+
"aliases": [
117+
"Transport Conditions"
118+
]
119+
}
120+
```
121+
122+
### Solution C1
123+
124+
- Remove `commitment` object
125+
- Remove `writer` field
126+
- Update `object` to `topic` field
127+
- Update `audience` to `obligee` field
128+
- Update `also known as` to `aliases` field
129+
- Add `indutries` field
130+
- Add `jurisdictions` field
131+
132+
#### Schema
133+
134+
```json
135+
"<terms type name>": {
136+
"topic": "...",
137+
"obligee": "...",
138+
"indutries": [ // Optional array of strings
139+
"..."
140+
],
141+
"jurisdictions": [ // Optional array of ISO 3166-2 region codes
142+
"..."
143+
],
144+
"aliases": [ // Optional array of strings
145+
"..."
146+
],
147+
"references": { // Optional object with name/url pairs
148+
"name": "url"
149+
}
150+
}
151+
```
152+
153+
##### Examples
154+
155+
```json
156+
"Editorial Policy": {
157+
"topic": "writing and publishing standards and principles",
158+
"obligee": "end user",
159+
"aliases": [
160+
"Editorial Guidelines"
161+
],
162+
"references": {
163+
"Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/35"
164+
}
165+
}
166+
```
167+
168+
```json
169+
"Conditions of Carriage": {
170+
"topic": "benefits and limitations associated with the transportation being provided",
171+
"obligee": "passenger",
172+
"indutries": [
173+
"Air Transport",
174+
"Maritime Transport",
175+
"Rail Transport",
176+
"Road Freight and Trucking",
177+
"Public Transit (Bus, Metro)",
178+
"Delivery and Courier Services"
179+
],
180+
"aliases": [
181+
"Transport Conditions"
182+
]
183+
}
184+
```
185+
186+
```json
187+
"Anti-corruption Policy": {
188+
"topic": "risk mitigation and prevention of involvement in bribery",
189+
"obligee": "any person working directly or indirectly for the service provider",
190+
"jurisdictions": [
191+
"US",
192+
"GB",
193+
"FR"
194+
],
195+
"aliases": [
196+
"Anti-bribery Policy"
197+
],
198+
"references": {
199+
"Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/39",
200+
"🇺🇸 Foreign Corrupt Practices Act": "https://www.justice.gov/criminal/criminal-fraud/foreign-corrupt-practices-act",
201+
"🇬🇧 Bribery Act 2010": "https://www.legislation.gov.uk/ukpga/2010/23/contents",
202+
"🇫🇷 Loi n°2016-1691 du 9 décembre 2016 relative à la transparence, à la lutte contre la corruption et à la modernisation de la vie économique, dite « Sapin II »": "https://www.legifrance.gouv.fr/loda/id/JORFTEXT000033558528",
203+
"ISO 37001 Anti-bribery management systems": "https://www.iso.org/iso-37001-anti-bribery-management.html"
204+
},
205+
}
206+
```
207+
208+
### Solution C2
209+
210+
- Include all C1 solution changes
211+
- Update `obligee` field to an array and make it plural `obligees`
212+
- Add `applicability` to nest `obligees`, `jurisdictions` and `industries` fields
213+
214+
#### Schema
215+
216+
```json
217+
"<terms type name>": {
218+
"topic": "...",
219+
"aliases": [ // Optional array of strings
220+
"..."
221+
],
222+
"applicability": { // Optional object defining scope
223+
"obligee": [ // Array of strings defining the parties obligated by the terms
224+
"..."
225+
],
226+
"jurisdictions": [ // Array of ISO 3166-2 region codes
227+
"..."
228+
],
229+
"industries": [ // Array of strings
230+
"..."
231+
]
232+
},
233+
"references": { // Optional object with name/url pairs
234+
"name": "url"
235+
}
236+
}
237+
```
238+
239+
##### Examples
240+
241+
```json
242+
"Editorial Policy": {
243+
"topic": "writing and publishing standards and principles",
244+
"aliases": [
245+
"Editorial Guidelines"
246+
],
247+
"applicability": {
248+
"obligee": [
249+
"end user",
250+
"content contributors"
251+
]
252+
},
253+
"references": {
254+
"Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/35"
255+
}
256+
}
257+
```
258+
259+
```json
260+
"Conditions of Carriage": {
261+
"topic": "benefits and limitations associated with the transportation being provided",
262+
"aliases": [
263+
"Transport Conditions"
264+
],
265+
"applicability": {
266+
"obligee": [
267+
"passenger",
268+
"sender"
269+
],
270+
"industries": [
271+
"Air Transport",
272+
"Maritime Transport",
273+
"Rail Transport",
274+
"Road Freight and Trucking",
275+
"Public Transit (Bus, Metro)",
276+
"Delivery and Courier Services"
277+
]
278+
}
279+
}
280+
```
281+
282+
```json
283+
"Anti-corruption Policy": {
284+
"topic": "risk mitigation and prevention of involvement in bribery",
285+
"aliases": [
286+
"Anti-bribery Policy"
287+
],
288+
"applicability": {
289+
"obligee": [
290+
"employees",
291+
"contractors",
292+
"partners"
293+
],
294+
"jurisdictions": [
295+
"US",
296+
"GB",
297+
"FR"
298+
]
299+
},
300+
"references": {
301+
"Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/39",
302+
"🇺🇸 Foreign Corrupt Practices Act": "https://www.justice.gov/criminal/criminal-fraud/foreign-corrupt-practices-act",
303+
"🇬🇧 Bribery Act 2010": "https://www.legislation.gov.uk/ukpga/2010/23/contents",
304+
"🇫🇷 Loi n°2016-1691 du 9 décembre 2016 relative à la transparence, à la lutte contre la corruption et à la modernisation de la vie économique, dite « Sapin II »": "https://www.legifrance.gouv.fr/loda/id/JORFTEXT000033558528"
305+
}
306+
}
307+
```
308+
309+
## Decision Outcome
310+
311+
[After consulting the community](https://github.com/OpenTermsArchive/terms-types/pull/85), the solution C1 is retained.

0 commit comments

Comments
 (0)