@opentermsarchive/engine 4.2.0 → 5.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Open Terms Archive Engine
 
-This codebase is a Node.js module enabling downloading, archiving and publishing versions of documents obtained online. It can be used independently from the Open Terms Archive ecosystem. For a high-level overview of Open Terms Archive’s wider goals and processes, please read its [public homepage](https://opentermsarchive.org).
+This codebase is a Node.js module enabling downloading, archiving and publishing versions of terms obtained online. It can be used independently from the Open Terms Archive ecosystem. For a high-level overview of Open Terms Archive’s wider goals and processes, please read its [public homepage](https://opentermsarchive.org).
 
 For documentation, visit [docs.opentermsarchive.org](https://docs.opentermsarchive.org/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentermsarchive/engine",
-  "version": "4.2.0",
+  "version": "5.0.1",
   "description": "Tracks and makes visible changes to the terms of online services",
   "homepage": "https://opentermsarchive.org",
   "bugs": {

package/scripts/declarations/utils/fixtures/serviceA.json

@@ -1,6 +1,6 @@
 {
   "name": "Service",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://domain.example/tos",
       "select": "body"

package/scripts/declarations/utils/fixtures/serviceAMultipleTermsUpdated.json

@@ -1,6 +1,6 @@
 {
   "name": "Service",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://domain.example/tos",
       "select": "body",

package/scripts/declarations/utils/fixtures/serviceATermsAdded.json

@@ -1,6 +1,6 @@
 {
   "name": "Service",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://domain.example/tos",
       "select": "body"

package/scripts/declarations/utils/fixtures/serviceATermsRemoved.json

@@ -1,6 +1,6 @@
 {
   "name": "Service",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://domain.example/tos",
       "select": "body"

package/scripts/declarations/utils/fixtures/serviceATermsUpdated.json

@@ -1,6 +1,6 @@
 {
   "name": "Service",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://domain.example/tos",
       "select": "body",

package/scripts/declarations/utils/fixtures/serviceB.json

@@ -1,6 +1,6 @@
 {
   "name": "Service B",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://domain.example/tos",
       "select": "body"

package/scripts/declarations/utils/index.js

@@ -50,14 +50,14 @@ export default class DeclarationUtils {
       if (modifiedFilePath.endsWith('.filters.js')) {
         const declaration = await this.getJSONFromFile(this.defaultBranch, `declarations/${serviceId}.json`);
 
-        servicesTermsTypes[serviceId] = Object.keys(declaration.documents); // Considering how rarely filters are used, simply return all term types that could potentially be impacted to spare implementing a function change check
+        servicesTermsTypes[serviceId] = Object.keys(declaration.terms); // Considering how rarely filters are used, simply return all term types that could potentially be impacted to spare implementing a function change check
 
         return;
       }
 
       const originalService = await this.getJSONFromFile(this.defaultBranch, modifiedFilePath);
       const modifiedService = await this.getJSONFromFile('HEAD', modifiedFilePath);
-      const modifiedServiceTermsTypes = Object.keys(modifiedService.documents);
+      const modifiedServiceTermsTypes = Object.keys(modifiedService.terms);
 
       if (!originalService) {
         servicesTermsTypes[serviceId] = modifiedServiceTermsTypes;
@@ -65,11 +65,11 @@ export default class DeclarationUtils {
         return;
       }
 
-      const originalServiceTermsTypes = Object.keys(originalService.documents);
+      const originalServiceTermsTypes = Object.keys(originalService.terms);
 
       modifiedServiceTermsTypes.forEach(termsType => {
         const areTermsAdded = !originalServiceTermsTypes.includes(termsType);
-        const areTermsModified = JSON.stringify(originalService.documents[termsType]) != JSON.stringify(modifiedService.documents[termsType]);
+        const areTermsModified = JSON.stringify(originalService.terms[termsType]) != JSON.stringify(modifiedService.terms[termsType]);
 
         if (!areTermsAdded && !areTermsModified) {
           return;

package/scripts/declarations/validate/service.schema.js

@@ -24,14 +24,14 @@ const schema = {
   type: 'object',
   additionalProperties: false,
   title: 'Service declaration',
-  required: [ 'name', 'documents' ],
+  required: [ 'name', 'terms' ],
   properties: {
     name: {
       type: 'string',
       title: 'Service public name',
       examples: ['Facebook'],
     },
-    documents: {
+    terms: {
       type: 'object',
       properties: termsProperties(),
       propertyNames: { enum: AVAILABLE_TYPES_NAME },

package/scripts/metadata/index.mocha.js

@@ -71,7 +71,12 @@ describe('Metadata file validation', () => {
         return `- ${basePath}: "${actualValue}" ${formatMessages[error.params.format]}`;
       }
 
-      let message = `- ${basePath}: "${actualValue}" ${error.message}`;
+      let message = `- ${basePath}:`;
+
+      if (actualValue !== undefined && typeof actualValue !== 'object') {
+        message += ` "${actualValue}"`;
+      }
+      message += ` ${error.message}`;
 
       if (error.keyword === 'enum') {
         message += ` "${error.params.allowedValues.join('", "')}"`;

package/src/archivist/services/index.js

@@ -21,7 +21,7 @@ export async function load(servicesIdsToLoad = []) {
   const services = {};
 
   await Promise.all(servicesIds.map(async serviceId => {
-    const { name, documents: terms } = await loadServiceDeclaration(serviceId);
+    const { name, terms } = await loadServiceDeclaration(serviceId);
 
     const service = new Service({ id: serviceId, name });
 
@@ -220,9 +220,9 @@ async function loadServiceHistoryFiles(serviceId) {
     }
   }
 
-  Object.keys(serviceDeclaration.documents).forEach(termsType => {
+  Object.keys(serviceDeclaration.terms).forEach(termsType => {
     serviceHistory[termsType] = serviceHistory[termsType] || [];
-    serviceHistory[termsType].push(serviceDeclaration.documents[termsType]);
+    serviceHistory[termsType].push(serviceDeclaration.terms[termsType]);
   });
 
   sortHistory(serviceHistory);

package/src/archivist/services/terms.js

@@ -16,7 +16,7 @@ export default class Terms {
   toPersistence() {
     return {
       name: this.service.name,
-      documents: {
+      terms: {
         [this.type]: this.hasMultipleSourceDocuments
           ? { combine: this.sourceDocuments.map(sourceDocument => sourceDocument.toPersistence()) }
           : this.sourceDocuments[0].toPersistence(),

package/src/archivist/services/terms.test.js

@@ -65,7 +65,7 @@ describe('Terms', () => {
 
       const expectedResult = {
         name: service.name,
-        documents: { [termsType]: document1AsJSON },
+        terms: { [termsType]: document1AsJSON },
       };
 
       expect(result).to.deep.equal(expectedResult);
@@ -76,7 +76,7 @@ describe('Terms', () => {
 
       const expectedResult = {
         name: service.name,
-        documents: { [termsType]: { combine: [ document1AsJSON, document2AsJSON ] } },
+        terms: { [termsType]: { combine: [ document1AsJSON, document2AsJSON ] } },
       };
 
       expect(result).to.deep.equal(expectedResult);

package/src/collection-api/routes/metadata.js

@@ -20,110 +20,155 @@ const PACKAGE_JSON_PATH = '../../../package.json';
  *       type: object
  *       description: Collection metadata
  *       additionalProperties: false
+ *       required:
+ *         - id
+ *         - name
+ *         - tagline
+ *         - languages
+ *         - jurisdictions
  *       properties:
  *         id:
  *           type: string
- *           description: Unique identifier of the collection
+ *           description: Unique identifier derived from name (acronyms, dash-separated).
+ *           example: demo
  *         name:
  *           type: string
- *           description: Display name of the collection
+ *           description: Display name of the collection.
+ *           example: Demo Collection
  *         tagline:
  *           type: string
- *           description: Short description of the collection
+ *           description: Concise description of collection topic.
+ *           example: Services used by Open Terms Archive
+ *         languages:
+ *           type: array
+ *           description: List of [ISO 639-1 (two-letter)](https://en.wikipedia.org/wiki/ISO_639) language codes representing languages allowed in the collection.
+ *           example: [en, fr, de]
+ *           items:
+ *             type: string
+ *             format: iso639-1
+ *         jurisdictions:
+ *           type: array
+ *           description: List of [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) representing jurisdictions covered by the collection.
+ *           example: [EU]
+ *           items:
+ *             type: string
+ *             format: iso3166-2
  *         description:
  *           type: string
- *           nullable: true
  *           description: Detailed description of the collection
+ *           example: |
+ *             The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.
+ *
+ *             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.
  *         totalTerms:
  *           type: integer
- *           description: Total number of terms tracked in the collection
+ *           description: Total number of terms tracked in the collection.
+ *           x-ota-generated: true
  *         totalServices:
  *           type: integer
- *           description: Total number of services tracked in the collection
+ *           description: Total number of services tracked in the collection.
+ *           x-ota-generated: true
  *         engineVersion:
  *           type: string
- *           description: Version of the Open Terms Archive engine in SemVer format (MAJOR.MINOR.PATCH)
+ *           description: Version of the Open Terms Archive engine in SemVer format (MAJOR.MINOR.PATCH).
+ *           x-ota-generated: true
  *         dataset:
  *           type: string
  *           format: uri
- *           description: URL to the dataset releases
+ *           description: URL to the dataset releases.
+ *           example: https://github.com/OpenTermsArchive/demo-versions/releases
  *         declarations:
  *           type: string
  *           format: uri
- *           description: URL to the declarations repository
+ *           description: URL to the declarations repository.
+ *           example: https://github.com/OpenTermsArchive/demo-declarations
  *         versions:
  *           type: string
  *           format: uri
- *           description: URL to the versions repository
+ *           description: URL to the versions repository.
+ *           example: https://github.com/OpenTermsArchive/demo-versions
  *         snapshots:
  *           type: string
  *           format: uri
- *           description: URL to the snapshots repository
+ *           description: URL to the snapshots repository.
+ *           example: https://github.com/OpenTermsArchive/demo-snapshots
  *         donations:
  *           type: string
  *           format: uri
- *           description: URL to the donations page
+ *           description: URL to the donations page.
+ *           example: https://opencollective.com/opentermsarchive
  *         logo:
  *           type: string
  *           format: uri
- *           nullable: true
- *           description: URL to the collection logo
- *         languages:
- *           type: array
- *           description: List of ISO 639-1 (two-letter) language codes representing languages allowed by the collection
- *           items:
- *             type: string
- *             format: iso639-1
- *         jurisdictions:
- *           type: array
- *           description: List of ISO 3166-2 country codes representing jurisdictions covered by the collection
- *           items:
- *             type: string
- *             format: iso3166-2
+ *           description: URL to the collection's logo. Optimized PNG transparent image (minimum width 240px).
+ *           example: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
  *         trackingPeriods:
  *           type: array
+ *           description: List of time periods during which terms were tracked, with their tracking configuration. Gaps between periods indicate times when tracking was interrupted.
  *           items:
  *             type: object
  *             additionalProperties: false
+ *             required:
+ *               - startDate
+ *               - schedule
+ *               - serverLocation
  *             properties:
  *               startDate:
  *                 type: string
  *                 format: date
- *                 description: The date when tracking started for this period
+ *                 description: The date when tracking started for this period (ISO 8601 format YYYY-MM-DD).
+ *                 example: 2023-01-01
  *               schedule:
  *                 type: string
  *                 format: cron-expression
- *                 description: A cron expression defining when terms are tracked (e.g. "0 0 * * *" for daily at midnight)
+ *                 description: A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency.
+ *                 example: 0 0 * * *
  *               serverLocation:
  *                 type: string
- *                 description: The geographic location of the server used for tracking
+ *                 description: The geographic location of the tracking server (city name and ISO 3166-2 country code).
+ *                 example: Paris, FR
  *               endDate:
  *                 type: string
  *                 format: date
- *                 description: The date when tracking ended for this period
+ *                 description: The date when tracking ended for this period (ISO 8601 format YYYY-MM-DD). If not specified, tracking is ongoing.
+ *                 example: 2023-12-01
  *         governance:
  *           type: object
+ *           description: Map of organizations involved in the collection's governance, with organization names as keys and governance objects as values.
  *           additionalProperties:
  *             type: object
  *             additionalProperties: false
+ *             required:
+ *               - roles
  *             properties:
  *               url:
  *                 type: string
  *                 format: uri
  *                 description: URL to the entity's website
+ *                 example: https://opentermsarchive.org/
  *               logo:
  *                 type: string
  *                 format: uri
- *                 description: URL to the entity's logo
+ *                 description: URL to the entity's logo. Optimized PNG transparent image (minimum width 240px).
+ *                 example: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
  *               roles:
  *                 type: array
+ *                 description: Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)
+ *                 example: [host, administrator]
  *                 items:
  *                   type: string
  *                   enum: [host, administrator, curator, maintainer, sponsor]
- *                   description: Roles of the entity within the governance
  *         i18n:
  *           type: object
  *           description: Internationalization of any of the Metadata properties (except i18n itself) for different language codes
+ *           example: |
+ *             fr:
+ *               name: Démo
+ *               tagline: Services utilisés par Open Terms Archive
+ *               governance:
+ *                 Ministry for Europe and Foreign Affairs:
+ *                   name: Ministère de l'Europe et des Affaires étrangères
+ *                   url: https://www.diplomatie.gouv.fr
  *           additionalProperties:
  *             type: object
  */