1---
 2layout: page
 3title: New schema for Lexicon artifacts
 4---
 5
 6- **ADR:** 0021
 7- **Proposal Author(s):** @eddie-knight
 8- **Status:** Accepted
 9
10## Context
11
12We currently have a field in all documents for `Metadata.Lexicon`, which is an `ArtifactMapping` type. This allows authors to link out to another document for their definitions. We do not, however, have any opinion on what that document looks like.
13
14Gemara user [OSPS Baseline](https://baseline.openssf.org) uses a custom YAML schema to hold their definitions, which is then used when generating the project's Markdown web page. The generator inspects the text fields of every control and requirement, then wraps any lexicon terms in a link which enables users to jump directly to the definition.  
15
16## Action
17
18Create a new lexicon schema inspired by the OSPS Basline Lexicon. It should behave like all other artifact schemas, such as the presence of `Metadata`. 
19
20Similar to mapping documents, this should not be affiliated with a Gemara Model Layer.
21
22The body of the document should be approximately:
23
24- title
25- definition
26- synonyms (optional, used for linking logic)
27- references (optional, functions like citations for the definition)
28
29## Consequences
30
31Positive: Fills the gap created by `Metadata.Lexicon`. Allows official Gemara tooling to behave similar to how users are currently operating.
32
33Negative: Yet another schema.
34
35## Alternatives Considered
36
37None