# ADAC Specification Style Guide
### Authoring Conventions for ADAC Core and Profile Documents

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | Stable |
| **Date** | 2026 |
| **Lead Author** | John Vaden |

*© 2026 InnoVadens, LLC. All rights reserved.*

---

## Abstract

This document defines the editorial conventions, structural patterns, and formatting rules that govern every Archival Digital Asset Container (ADAC) specification document — from the core format specification to each domain profile extension. It ensures terminological consistency, predictable document layout, uniform JSON schema conventions, and clear normative language so that implementers encounter a single, coherent authoring voice across the entire ADAC family. All ADAC specification authors, technical editors, and profile extension designers are expected to follow the conventions set forth herein.

---

## Table of Contents

1. [Introduction](#1-introduction)
2. [Normative Language](#2-normative-language)
3. [Document Structure](#3-document-structure)
4. [Terminology Conventions](#4-terminology-conventions)
5. [JSON Conventions](#5-json-conventions)
6. [Profile Wrapper Requirements](#6-profile-wrapper-requirements)
7. [Writing Style](#7-writing-style)
8. [Interoperability Guidance](#8-interoperability-guidance)
9. [Versioning Rules](#9-versioning-rules)
10. [References](#10-references)
- [Version History](#version-history)

---

## 1. Introduction

### 1.1 Purpose

The ADAC ecosystem comprises a core format specification and an open-ended family of domain profile extensions (e.g., ADAC-Genealogy, ADAC-Legal). As the family grows, consistency across documents becomes critical for implementers, who must be able to navigate any ADAC specification with the same expectations regarding structure, terminology, and conventions. This style guide codifies the conventions that every ADAC specification author **MUST** follow, covering document structure, normative language, terminology, JSON schema formatting, and versioning.

### 1.2 Scope

This guide applies to:

- The ADAC Format Specification (core)
- All official ADAC profile extension specifications (ADAC-Genealogy, ADAC-Legal, and future profiles)
- Companion documents such as API documentation, CLI documentation, and implementation guides

This guide does **not** govern end-user application interfaces, marketing materials, or community-contributed tutorials unless they carry the official ADAC designation.

### 1.3 Audience

Specification authors, technical editors, profile extension designers, and anyone contributing normative text to the ADAC document family.

---

## 2. Normative Language

### 2.1 RFC 2119 Keywords

ADAC specifications use the keywords defined in RFC 2119 and RFC 8174: **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL**. These keywords **MUST** appear in uppercase when conveying normative force. When used in lowercase, the word carries its ordinary English meaning and is non-normative.

### 2.2 Conformance Clause

Every ADAC specification **MUST** include a Conformance section that:

1. References RFC 2119 and RFC 8174
2. Defines conformance levels if applicable
3. States the normative status of each section

### 2.3 Normative vs. Informative Text

Normative sections impose requirements on implementations. Informative sections aid understanding but carry no conformance weight.

> **Convention:** Use `NOTE —` for informative asides and `EXAMPLE —` for illustrative code or data.

---

## 3. Document Structure

### 3.1 Required Sections (Core Spec)

The ADAC Format Specification **MUST** present sections in the following order:

1. Title Block
2. Abstract
3. Table of Contents
4. Introduction
5. Conformance
6. Terminology
7. Architecture
8. Technical Sections
9. Complete Container Example
10. References
11. Version History

### 3.2 Required Sections (Profile Extensions)

Each ADAC profile extension **MUST** present:

1. Title Block
2. Abstract
3. Table of Contents
4. Introduction
5. Conformance
6. Terminology
7. Profile Metadata File Schema
8. Linked Entity Definitions
9. Region Annotation Extensions
10. Interoperability
11. Complete Profile Example
12. References
13. Version History

### 3.3 Section Numbering

Use decimal numbering up to three levels: §1, §1.1, §1.1.1.

### 3.4 Cross-References

Use `"see §N.N"`. Never reference page numbers.

---

## 4. Terminology Conventions

### 4.1 Defined Terms

Every specification **MUST** include a Terminology section. First use of a defined term **SHOULD** appear in **bold**.

### 4.2 Consistent Naming

| Preferred Term | Avoid |
|---|---|
| container | package, archive, bundle |
| master file | original, source file, primary |
| derivative | copy, rendition, version |
| region | zone, area, bounding box |
| linked entity | annotation payload, domain data |
| profile | plugin, module |
| provenance log | audit trail, history |
| fixity | integrity check |
| manifest | index, catalog |
| edit pipeline | edit stack |

### 4.3 Namespace Prefixes

Linked entity keys use the format:

```
namespace:type
```

**Example:** `genealogy:person`

---

## 5. JSON Conventions

### 5.1 Schema Language

Use JSON Schema Draft 2020-12.

### 5.2 Property Naming

Use `camelCase` for all JSON properties.

### 5.3 Date-Time Format

Use ISO 8601 with UTC offset:

```
2025-01-15T10:30:00Z
```

### 5.4 Identifiers

| Identifier Type | Format |
|---|---|
| Container IDs | UUID v4 |
| Internal IDs | kebab-case |
| Profile IDs | Namespaced when needed |

### 5.5 Enumerated Values

Use `kebab-case` for enums.

### 5.6 Null and Absent Fields

Absent and `null` are equivalent.

### 5.7 Extensibility

Profiles **MAY** add fields; core **MUST NOT**.

### 5.8 Example Formatting

All JSON examples must be:

- Valid JSON
- 2-space indented
- Captioned
- Treated as informative unless stated otherwise

---

## 6. Profile Wrapper Requirements

### 6.1 File Location

Profile metadata files reside at:

```
metadata/profiles/<profileName>.json
```

### 6.2 Wrapper Schema

**Required fields:**

| Field | Type | Description |
|---|---|---|
| `profileName` | string | Registered profile identifier |
| `profileVersion` | string | Profile version |
| `schemaRef` | string (URI) | JSON Schema reference |

### 6.3 Additive-Only Rule

Profiles **MUST NOT**:

- Redefine core fields
- Alter core semantics
- Modify `manifest.json` except to list the profile

### 6.4 Multi-Profile Coexistence

Namespaces prevent conflicts.

---

## 7. Writing Style

### 7.1 Voice and Tense

Use third-person, present-tense, active voice.

### 7.2 Sentence Structure

One requirement per sentence.

### 7.3 Lists

- **Numbered** for sequences
- **Bullets** for sets

### 7.4 Code and Markup

Use `monospace` for JSON keys and file paths.

### 7.5 Abbreviations

Spell out on first use.

---

## 8. Interoperability Guidance

### 8.1 Standards Alignment

Each specification **MUST** document external standards it aligns with.

### 8.2 Graceful Ignorance

Readers **MUST** ignore unknown profile data without error.

### 8.3 Round-Trip Fidelity

Implementations **MUST** preserve unrecognized fields.

---

## 9. Versioning Rules

### 9.1 Version Numbering

Use `MAJOR.MINOR` format.

### 9.2 Compatibility Guarantees

`adacVersion: "1.x"` **MUST** be readable by any ADAC 1.0 implementation.

### 9.3 Version History Section

Every specification **MUST** include a version history table in the following format:

| Version | Date | Summary of Changes |
|---|---|---|

### 9.4 Profile Versioning

Profiles maintain independent version numbers.

---

## 10. References

### 10.1 Normative References

- RFC 2119
- RFC 8174
- JSON Schema Draft 2020-12
- ISO 8601
- Dublin Core
- PREMIS

### 10.2 Informative References

- ZIP APPNOTE
- XMP
- GEDCOM 7
- PREMIS Implementation Guidelines

---

## Version History

| Version | Date | Summary of Changes |
|---|---|---|
| 1.0 | 2026 | Initial publication. |

---

*© 2026 InnoVadens, LLC. All rights reserved.*