Proposal for Schema Improvements

[clementbiron]

This PR is an experiment to create RFC that will lead to a decision record delivery.

The idea is to add comments right onto the document, much like you would with code. I will update the document for each consensus reached.

The deadline for this RFC is November 11 end of day AoE (Anywhere on Earth).

[MattiSG]

Thank you for this proposal! I think at this stage I have a slight preference for option 1, but let's see how this evolves 🙂

[Ndpnt]

What about a new field Applicability.

It could be something like this:

"Imprint": {
    "topic": "identification of content author and hosting service for official inquiries",
    …,
    "applicability": "Required in some regions, such as EU countries, for transparency and contact information"
  }

or

"Developer Terms": {
   "topic": "APIs and programmatic access to content",
   …,
   "applicability": "Restricted to developers or partners who use the service's APIs or development tools"
 },

[Ndpnt]

I support solution B because it offers a data structure optimized for a database rather than one designed to be read as a sentence. This structure is more suitable for coding, as it features clear, distinct fields that facilitate data manipulation and usage in programming contexts. While it may seem appealing to have data fields presented in a sentence format, I believe this approach offers minimal improvement in actual legibility and can compromise clarity when used in code. Especially since having fields that don't form a sentence does not reduce the understandability of the data structure, as the field names remain self-explanatory.

P.S. And If a more user-friendly presentation of the data is really required, creating a display interface to transform this structured data into readable sentences would be quite straightforward.

[clementbiron]

In my opinion, the industry or applicability field should show in which industry the use of the terms type has been identified, but not restrict its use to that industry. So the naming of the key should reflect this.

[Ndpnt]

In my opinion, the industry or applicability field should show in which industry the use of the terms type has been identified, but not restrict its use to that industry. So the naming of the key should reflect this.

What about having industry being an array:

"Marketplace Sellers Conditions": {
  "topic": "Selling goods or services on an online marketplace",
  "industry": [
    "e-commerce",
    "retail",
    "online services"
  ],
  "audience": "sellers",
  "aliases": [
    "Seller Agreement"
  ],
  "references": {
    "Marketplace Policies": "https://example.com/marketplace-policies"
  }
}

or

"Data Protection Policies": {
  "topic": "Guidelines for the protection of personal data",
  "industry": [
    "technology",
    "healthcare",
    "finance",
    "education"
  ],
  "audience": "businesses",
  "aliases": [
    "Data Privacy Policies",
    "GDPR Compliance Guidelines"
  ],
  "references": {
    "Data Protection Regulations": "https://example.com/data-protection-regulations",
    "Best Practices for Data Security": "https://example.com/data-security-best-practices"
  }
}

In this way, the data can be extended as and when required.

[MattiSG]

What about a new field Applicability.

That's a good idea! I was more thinking of a jurisdictions field, with an array of region codes. This could however also be added at a later stage as a minor version addition.

If you'd like to add it, could you rather use the code suggestion feature (or open a PR on top of that PR)? 🙂

[clementbiron]

What about a new field Applicability.

That's a good idea! I was more thinking of a jurisdictions field, with an array of region codes. This could however also be added at a later stage as a minor version addition.

If you'd like to add it, could you rather use the code suggestion feature (or open a PR on top of that PR)? 🙂

I would go for a jurisdictions field with an array of region codes because Applicability is for me a mixture of audience industry and topic fields. This seems to me to be a way of reformulating these 3 fields and I don't think it's necessary.

[clementbiron]

The discussion in the GitHub comments makes it difficult to summarise the current state of proposals. The core team is planning a discussion session (1 hour maximum) on Monday 4 November at 2pm UTC, open to anyone who wishes to take part to finalise the proposals that will be put to the vote. This will take place online here.

In the meantime, discussions will of course remain open here.

[clementbiron]

Following the sync call, i updated the proposals.

We welcome your feedback.

[Ndpnt]

Following the sync call, i updated the proposals.

We welcome your feedback.

Great to see that the synchronous call has paid off, I really like the solution C. 👏

I have two more suggestions to make:

• Change obligee field to an array to accommodates policies that involve multiple actors, such as agreements where both "end users" and "commercial partners" are affected for example. It would also allow easy expansion, such as adding new obligees in the future, without disrupting existing data.

• Nest obligee, jurisdictions, and industries under a applicability field. Grouping these fields in an applicability object emphasizes that these elements define the scope and context of the policy.

Solution C.2

"<terms type name>": {
  "topic": "...",
  "aliases": [ // Optional array of strings
    "..."
  ],
  "applicability": { // Optional object defining scope
    "obligee": [ // Array of strings defining the parties obligated by the terms
      "..."
    ],
    "jurisdictions": [ // Array of ISO 3166-2 region codes
      "..."
    ],
    "industries": [ // Array of strings
      "..."
    ]
  },
  "references": { // Optional object with name/url pairs
    "name": "url"
  }
}

Examples

1. Editorial Policy

"Editorial Policy": {
  "topic": "writing and publishing standards and principles",
  "aliases": [
    "Editorial Guidelines"
  ],
  "applicability": {
    "obligee": [
      "end user",
      "content contributors"
    ]
  },
  "references": {
    "Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/35"
  }
}

2. Conditions of Carriage

"Conditions of Carriage": {
  "topic": "benefits and limitations associated with the transportation being provided",
  "aliases": [
    "Transport Conditions"
  ],
  "applicability": {
    "obligee": [
      "passenger",
      "sender"
    ],
    "industries": [
      "Air Transport",
      "Maritime Transport",
      "Rail Transport",
      "Road Freight and Trucking",
      "Public Transit (Bus, Metro)",
      "Delivery and Courier Services"
    ]
  }
}

3. Anti-corruption Policy

"Anti-corruption Policy": {
  "topic": "risk mitigation and prevention of involvement in bribery",
  "aliases": [
    "Anti-bribery Policy"
  ],
  "applicability": {
    "obligee": [
      "employees",
      "contractors",
      "partners"
    ],
    "jurisdictions": [
      "US",
      "GB",
      "FR"
    ]
  },
  "references": {
    "Open Terms Archive discussion": "https://github.com/OpenTermsArchive/terms-types/discussions/39",
    "🇺🇸 Foreign Corrupt Practices Act": "https://www.justice.gov/criminal/criminal-fraud/foreign-corrupt-practices-act",
    "🇬🇧 Bribery Act 2010": "https://www.legislation.gov.uk/ukpga/2010/23/contents",
    "🇫🇷 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"
  }
}

[clementbiron]

Thank you @Ndpnt for this suggestion 👏

[clementbiron]

As the deadline is approaching, I'd like to invite everyone to vote by 11 November AoE.

As a reminder, there are 4 proposals A, B, C1, C2

Please indicate your choice in the comments.

[Ndpnt]

I vote for C2!

[MattiSG]

I vote for C1.

[clementbiron]

I also vote for C1.

[clementbiron]

Thank you all for your participation.

Solution C1 has been selected.