Rename documents key to terms in service declarations for vocabulary consistency

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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 file. This codebase adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased [major]
+
+> Development of this release was supported by the [French Ministry for Foreign Affairs](https://www.diplomatie.gouv.fr/fr/politique-etrangere-de-la-france/diplomatie-numerique/) through its ministerial [State Startups incubator](https://beta.gouv.fr/startups/open-terms-archive.html) under the aegis of the Ambassador for Digital Affairs.
+
+### Changed
+
+- **Breaking:** Rename `documents` key to `terms` in service declarations for vocabulary consistency; update your service declarations accordingly. You can update your declarations by executing the following command at the root of your declarations folder: `find . -name "*.json" -type f -exec sed -i 's/"documents":/"terms":/g' {} +` for Unix-like systems, or `find . -name "*.json" -type f -exec sed -i '' 's/"documents":/"terms":/g' {} +` for macOS
+
 ## 4.2.0 - 2025-02-17
 
 _Full changeset and discussions: [#1135](https://github.com/OpenTermsArchive/engine/pull/1135)._

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/)
 

scripts/declarations/utils/fixtures/serviceA.json

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

scripts/declarations/utils/fixtures/serviceAMultipleTermsUpdated.json

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

scripts/declarations/utils/fixtures/serviceATermsAdded.json

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

scripts/declarations/utils/fixtures/serviceATermsRemoved.json

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

scripts/declarations/utils/fixtures/serviceATermsUpdated.json

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

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"

scripts/declarations/utils/index.js

@@ -50,26 +50,26 @@ 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;
 
         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;

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 },

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);

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(),

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);

test/test-declarations/declarations/Service B!.json

@@ -1,6 +1,6 @@
 {
   "name": "Service B!",
-  "documents": {
+  "terms": {
     "Privacy Policy": {
       "fetch": "https://www.serviceb.example/privacy",
       "select": "body"

test/test-declarations/declarations/service_with_declaration_history.json

@@ -1,6 +1,6 @@
 {
   "name": "Service with declaration history",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://www.service-with-declaration-history.example/terms",
       "select": "main",

test/test-declarations/declarations/service_with_filters_history.json

@@ -1,6 +1,6 @@
 {
   "name": "Service with filters history",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://www.service-with-filters-history.example/terms",
       "select": "main",

test/test-declarations/declarations/service_with_history.json

@@ -1,6 +1,6 @@
 {
   "name": "Service with history",
-  "documents": {
+  "terms": {
     "Terms of Service": {
       "fetch": "https://www.service-with-history.example/terms",
       "select": "main",

test/test-declarations/declarations/service_with_multiple_source_documents_terms.json

@@ -1,6 +1,6 @@
 {
   "name": "Service with terms with multiple source documents",
-  "documents": {
+  "terms": {
     "Community Guidelines": {
       "combine": [
         {

test/test-declarations/declarations/service_without_history.json

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

test/test-declarations/declarations/service·A.json

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