You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
2.**Peer Review:** The PR must be reviewed and approved by **at least two or three Domain Editors**. To ensure cross-functional alignment and prevent siloed terminology, this group of reviewers **must include Domain Editors from different Technical Working Groups** (e.g., at least one Editor from the primary seeding/aligned WG and at least one Editor from a related/cross-cutting WG, such as Security & Privacy or Governance).
37
-
3.**Final Merge:** Once the required cross-workgroup approvals (at least 2 or 3 Domain Editors) are secured, one of the Co-Chairs will perform a final administrative review and click **Merge** to deploy the update to the live portal.
19
+
## 2. Contribution Pathways
20
+
21
+
We support two ways to contribute to the taxonomy and landscape:
22
+
23
+
***Option A: The Git & Pull Request Workflow (Code Contributors):** Best for technical domain editors. You will clone the repo, make edits directly to the data files, run a local preview web server to test, and submit a PR.
24
+
* 👉 For step-by-step instructions on setting up Git, starting a local server, and submitting PRs, see the **[Local Development & Git Workflow Guide](docs/local-development.md)**.
25
+
***Option B: The Asynchronous Proposal Workflow (General Contributors):** If you prefer not to write code or use Git, you can propose glossary additions or landscape tools by opening an issue on our GitHub Issues page.
26
+
* 👉 Follow the templates on our Issues page to submit the raw details, and a Domain Editor will review and merge them on your behalf.
27
+
28
+
---
29
+
30
+
## 3. Data Schema Guidelines
31
+
32
+
To ensure automated builds and parsing pipelines run successfully, all additions must strictly adhere to our metadata schemas.
33
+
***Taxonomy Glossary:** Uses a SKOS-Lite-compliant schema mapping display terms, categories, parent nodes (`broaderTerm`), definitions, and aligned working groups.
34
+
***Ecosystem Landscape:** Follows a CNCF-style structure mapping tools, protocols, and regulatory bodies to categories.
35
+
* 👉 For field-by-field specifications, enum lists, and code examples, see the **[Data Schema Specifications & Guidelines](docs/data-schemas.md)**.
36
+
37
+
---
38
+
39
+
## 4. Collaborative PR Curation Workflow
40
+
41
+
Once a Pull Request is opened:
42
+
43
+
1.**Peer Review:** The PR must be reviewed and approved by **at least two or three Domain Editors**. To ensure cross-functional alignment and prevent siloed terminology, this group of reviewers **must include Domain Editors from different Technical Working Groups** (e.g., at least one Editor from the primary seeding/aligned WG and at least one Editor from a related/cross-cutting WG, such as Security & Privacy or Governance).
44
+
2.**Final Merge:** Once the required cross-workgroup approvals are secured, one of the Co-Chairs (Junjie or Gala) will perform a final administrative review and merge the PR.
To maintain a high-quality, cohesive vocabulary across the foundation, all proposed taxonomy terminology must meet strict criteria and follow a structured consensus process.
44
51
45
52
### A. Terminology Acceptance Criteria
46
53
For any new glossary term to be approved and merged, it must satisfy the following:
47
-
1.**Pre-Competitive & Neutral:** Definitions must be vendor-neutral, objective, and clear. Proprietary product names, marketing jargon, or biased terminology are strictly prohibited.
48
-
2.**Technical Precision & Clarity:** The term must be clearly defined with technical utility. Avoid overly broad definitions that lack concrete boundaries.
49
-
3.**Uniqueness (De-duplication):** The term must not duplicate existing concepts. If a proposed term is a synonym of an existing term, it must be added as an entry in the `aliases` array of the existing term rather than creating a new entry.
50
-
4.**Schema Compliance:** The metadata structure must strictly conform to the SKOS-Lite specification (including category, workgroups, broaderTerm, and a precise definition and scopeNote).
54
+
1.**High-Level Scope Alignment:** The term must represent a cross-cutting concept (affecting $\ge$ 2 WGs) or be foundational to the entire AAIF ecosystem. Specialized, single-WG terms should remain in their respective WG repositories (see the Index vs. Payload boundaries in the [Charter](charter/charter.md)).
55
+
2.**Pre-Competitive & Neutral:** Definitions must be vendor-neutral, objective, and clear. Proprietary product names, marketing jargon, or biased terminology are strictly prohibited.
56
+
3.**Technical Precision & Clarity:** The term must be clearly defined with technical utility. Avoid overly broad definitions that lack concrete boundaries.
57
+
4.**Uniqueness (De-duplication & Anti-Erasure):** The term must not duplicate existing concepts. If a proposed term is a genuine synonym of an existing term, it must be added as an entry in the `aliases` array of the existing term. **CRITICAL GUARDRAIL:** Do NOT fold a look-alike term into an alias of another term without explicit written sign-off from the owning Working Group's **Domain Editor**. If terms look similar but represent deliberately distinct concepts (e.g., *deterministic workflow* vs. *agentic workflow*), they must be preserved as separate entries.
58
+
5.**Schema Compliance:** The metadata structure must strictly conform to the specifications outlined in the [Schema Guide](docs/data-schemas.md).
51
59
52
60
### B. Decision-Making & Consensus Process
53
61
We prioritize rough consensus across the AAIF community:
@@ -57,37 +65,10 @@ We prioritize rough consensus across the AAIF community:
57
65
### C. Cross-Workgroup Conflict Resolution & Arbitration
58
66
Because terms often intersect (e.g., *Attestation* or *Agent* might have slightly different meanings in the Security WG vs. the Identity & Trust WG), we use the following conflict resolution protocol:
59
67
1.**Joint Collaboration (PR Phase):** If a Domain Editor flags a conceptual conflict, the primary seeding editor and the objecting editor must collaborate directly in the PR discussion to find a unified definition or refine the `scopeNote` to document the different perspectives.
60
-
2.**Partitioning & Hierarchies:** If a single term cannot represent both perspectives, editors should use `broaderTerm` hierarchy or specify context within the term name (e.g., *Security Attestation* vs. *Identity Attestation*).
61
-
3.**Chair Arbitration:** If Domain Editors cannot reach consensus within 14 days, the Workstream Chairs (Junjie & Gala) will mediate a resolution, choosing a compromise or scheduling a dedicated sync.
62
-
4.**TSC Escalation:** As a final resort, unresolved issues are escalated to the AAIF Technical Steering Committee (TSC) and the Foundation CTO (Manik) for a binding decision.
63
-
64
-
---
65
-
66
-
## 4. Data File Guidelines
67
-
68
-
### Taxonomy Entries (`taxonomy-data.js`)
69
-
Every new glossary entry must conform to the SKOS-Lite metadata structure:
70
-
```javascript
71
-
{
72
-
"term":"Preferred Display Term",
73
-
"category":"WG-Aligned Category Bucket",
74
-
"aliases": ["Synonym 1", "Synonym 2"],
75
-
"broaderTerm":"Parent Concept Term (if hierarchical)",
description: Short, neutral, non-marketing blurb describing the tool or standard.
89
-
project: graduated | incubating | member | external
90
-
```
68
+
2.**Paired Contrast Disambiguation (`skos:related` / `contrastsWith`):** When two terms represent distinct but complementary or contrasting concepts (e.g., *Tool* vs. *Skill*, *Primitive* vs. *Protocol*, or *Deterministic workflow* vs. *Agentic workflow*), a shared `scopeNote` combining both views writes down confusion rather than resolving it. Instead, **each term's definition MUST explicitly state how it differs from its counterpart**, and the pair MUST be linked using `relatedTerms` (`skos:related`) or `contrastsWith`.
69
+
3.**Partitioning & Hierarchies:** If a single term cannot represent both perspectives, editors should use `broaderTerm` hierarchy or specify context within the term name (e.g., *Security Attestation* vs. *Identity Attestation*).
70
+
4.**Chair Arbitration:** If Domain Editors cannot reach consensus within 14 days, the Workstream Chairs (Junjie & Gala) will mediate a resolution, choosing a compromise or scheduling a dedicated sync.
71
+
5.**TSC Escalation:** As a final resort, unresolved issues are escalated to the AAIF Technical Steering Committee (TSC) and the Foundation CTO (Manik) for a binding decision.
0 commit comments