@opentermsarchive/engine 5.0.0 → 5.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/scripts/metadata/index.mocha.js +10 -2
  3. package/src/collection-api/routes/metadata.js +77 -32
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opentermsarchive/engine",
3
- "version": "5.0.0",
3
+ "version": "5.0.2",
4
4
  "description": "Tracks and makes visible changes to the terms of online services",
5
5
  "homepage": "https://opentermsarchive.org",
6
6
  "bugs": {
package/scripts/metadata/index.mocha.js CHANGED
@@ -41,7 +41,10 @@ describe('Metadata file validation', () => {
41
41
 
42
42
  metadata = yaml.load(metadataContent, { schema: yaml.CORE_SCHEMA }); // Use CORE_SCHEMA to parse dates as strings rather than JavaScript Date objects
43
43
 
44
- const ajv = new Ajv({ allErrors: true });
44
+ const ajv = new Ajv({
45
+ allErrors: true,
46
+ strict: false, // Allow to ignore OpenAPI-specific keywords that aren't part of the JSON Schema specification (like `example`)
47
+ });
45
48
 
46
49
  addFormats(ajv);
47
50
 
@@ -71,7 +74,12 @@ describe('Metadata file validation', () => {
71
74
  return `- ${basePath}: "${actualValue}" ${formatMessages[error.params.format]}`;
72
75
  }
73
76
 
74
- let message = `- ${basePath}: "${actualValue}" ${error.message}`;
77
+ let message = `- ${basePath}:`;
78
+
79
+ if (actualValue !== undefined && typeof actualValue !== 'object') {
80
+ message += ` "${actualValue}"`;
81
+ }
82
+ message += ` ${error.message}`;
75
83
 
76
84
  if (error.keyword === 'enum') {
77
85
  message += ` "${error.params.allowedValues.join('", "')}"`;
package/src/collection-api/routes/metadata.js CHANGED
@@ -20,110 +20,155 @@ const PACKAGE_JSON_PATH = '../../../package.json';
20
20
  * type: object
21
21
  * description: Collection metadata
22
22
  * additionalProperties: false
23
+ * required:
24
+ * - id
25
+ * - name
26
+ * - tagline
27
+ * - languages
28
+ * - jurisdictions
23
29
  * properties:
24
30
  * id:
25
31
  * type: string
26
- * description: Unique identifier of the collection
32
+ * description: Unique identifier derived from name (acronyms, dash-separated).
33
+ * example: demo
27
34
  * name:
28
35
  * type: string
29
- * description: Display name of the collection
36
+ * description: Display name of the collection.
37
+ * example: Demo Collection
30
38
  * tagline:
31
39
  * type: string
32
- * description: Short description of the collection
40
+ * description: Concise description of collection topic.
41
+ * example: Services used by Open Terms Archive
42
+ * languages:
43
+ * type: array
44
+ * description: List of [ISO 639-1 (two-letter)](https://en.wikipedia.org/wiki/ISO_639) language codes representing languages allowed in the collection.
45
+ * example: [en, fr, de]
46
+ * items:
47
+ * type: string
48
+ * format: iso639-1
49
+ * jurisdictions:
50
+ * type: array
51
+ * description: List of [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) representing jurisdictions covered by the collection.
52
+ * example: [EU]
53
+ * items:
54
+ * type: string
55
+ * format: iso3166-2
33
56
  * description:
34
57
  * type: string
35
- * nullable: true
36
58
  * description: Detailed description of the collection
59
+ * example: |
60
+ * The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.
61
+ *
62
+ * This provides a reference collection for best practices and enables the Open Terms Archive Core Team to be a user of the software it produces.
37
63
  * totalTerms:
38
64
  * type: integer
39
- * description: Total number of terms tracked in the collection
65
+ * description: Total number of terms tracked in the collection.
66
+ * x-ota-generated: true
40
67
  * totalServices:
41
68
  * type: integer
42
- * description: Total number of services tracked in the collection
69
+ * description: Total number of services tracked in the collection.
70
+ * x-ota-generated: true
43
71
  * engineVersion:
44
72
  * type: string
45
- * description: Version of the Open Terms Archive engine in SemVer format (MAJOR.MINOR.PATCH)
73
+ * description: Version of the Open Terms Archive engine in SemVer format (MAJOR.MINOR.PATCH).
74
+ * x-ota-generated: true
46
75
  * dataset:
47
76
  * type: string
48
77
  * format: uri
49
- * description: URL to the dataset releases
78
+ * description: URL to the dataset releases.
79
+ * example: https://github.com/OpenTermsArchive/demo-versions/releases
50
80
  * declarations:
51
81
  * type: string
52
82
  * format: uri
53
- * description: URL to the declarations repository
83
+ * description: URL to the declarations repository.
84
+ * example: https://github.com/OpenTermsArchive/demo-declarations
54
85
  * versions:
55
86
  * type: string
56
87
  * format: uri
57
- * description: URL to the versions repository
88
+ * description: URL to the versions repository.
89
+ * example: https://github.com/OpenTermsArchive/demo-versions
58
90
  * snapshots:
59
91
  * type: string
60
92
  * format: uri
61
- * description: URL to the snapshots repository
93
+ * description: URL to the snapshots repository.
94
+ * example: https://github.com/OpenTermsArchive/demo-snapshots
62
95
  * donations:
63
96
  * type: string
64
97
  * format: uri
65
- * description: URL to the donations page
98
+ * description: URL to the donations page.
99
+ * example: https://opencollective.com/opentermsarchive
66
100
  * logo:
67
101
  * type: string
68
102
  * format: uri
69
- * nullable: true
70
- * description: URL to the collection logo
71
- * languages:
72
- * type: array
73
- * description: List of ISO 639-1 (two-letter) language codes representing languages allowed by the collection
74
- * items:
75
- * type: string
76
- * format: iso639-1
77
- * jurisdictions:
78
- * type: array
79
- * description: List of ISO 3166-2 country codes representing jurisdictions covered by the collection
80
- * items:
81
- * type: string
82
- * format: iso3166-2
103
+ * description: URL to the collection's logo. Optimized PNG transparent image (minimum width 240px).
104
+ * example: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
83
105
  * trackingPeriods:
84
106
  * type: array
107
+ * description: List of time periods during which terms were tracked, with their tracking configuration. Gaps between periods indicate times when tracking was interrupted.
85
108
  * items:
86
109
  * type: object
87
110
  * additionalProperties: false
111
+ * required:
112
+ * - startDate
113
+ * - schedule
114
+ * - serverLocation
88
115
  * properties:
89
116
  * startDate:
90
117
  * type: string
91
118
  * format: date
92
- * description: The date when tracking started for this period
119
+ * description: The date when tracking started for this period (ISO 8601 format YYYY-MM-DD).
120
+ * example: 2023-01-01
93
121
  * schedule:
94
122
  * type: string
95
123
  * format: cron-expression
96
- * description: A cron expression defining when terms are tracked (e.g. "0 0 * * *" for daily at midnight)
124
+ * description: A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency.
125
+ * example: 0 0 * * *
97
126
  * serverLocation:
98
127
  * type: string
99
- * description: The geographic location of the server used for tracking
128
+ * description: The geographic location of the tracking server (city name and ISO 3166-2 country code).
129
+ * example: Paris, FR
100
130
  * endDate:
101
131
  * type: string
102
132
  * format: date
103
- * description: The date when tracking ended for this period
133
+ * description: The date when tracking ended for this period (ISO 8601 format YYYY-MM-DD). If not specified, tracking is ongoing.
134
+ * example: 2023-12-01
104
135
  * governance:
105
136
  * type: object
137
+ * description: Map of organizations involved in the collection's governance, with organization names as keys and governance objects as values.
106
138
  * additionalProperties:
107
139
  * type: object
108
140
  * additionalProperties: false
141
+ * required:
142
+ * - roles
109
143
  * properties:
110
144
  * url:
111
145
  * type: string
112
146
  * format: uri
113
147
  * description: URL to the entity's website
148
+ * example: https://opentermsarchive.org/
114
149
  * logo:
115
150
  * type: string
116
151
  * format: uri
117
- * description: URL to the entity's logo
152
+ * description: URL to the entity's logo. Optimized PNG transparent image (minimum width 240px).
153
+ * example: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
118
154
  * roles:
119
155
  * type: array
156
+ * description: Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)
157
+ * example: [host, administrator]
120
158
  * items:
121
159
  * type: string
122
160
  * enum: [host, administrator, curator, maintainer, sponsor]
123
- * description: Roles of the entity within the governance
124
161
  * i18n:
125
162
  * type: object
126
163
  * description: Internationalization of any of the Metadata properties (except i18n itself) for different language codes
164
+ * example: |
165
+ * fr:
166
+ * name: Démo
167
+ * tagline: Services utilisés par Open Terms Archive
168
+ * governance:
169
+ * Ministry for Europe and Foreign Affairs:
170
+ * name: Ministère de l'Europe et des Affaires étrangères
171
+ * url: https://www.diplomatie.gouv.fr
127
172
  * additionalProperties:
128
173
  * type: object
129
174
  */