ADAC Specification Style Guide

Authoring Conventions for ADAC Core and Profile Documents

© 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
2. Normative Language
3. Document Structure
4. Terminology Conventions
5. JSON Conventions
6. Profile Wrapper Requirements
7. Writing Style
8. Interoperability Guidance
9. Versioning Rules
10. References

• 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

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

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:

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:

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

© 2026 InnoVadens, LLC. All rights reserved.