Standards Markup Syntax

A SynC Standard is more than a document. It is a structured object: every requirement is an addressable element, every configurable choice is a typed field, every revision is diffable element-by-element, and every cross-reference resolves to another standard the system knows about. The markup is what gives a plain text file all of that — and those properties are what let a standard be configured for a project, updated without forcing readers to re-read it, and reliably cited across many projects.

Most of the syntax is standard markdown. A few SynC-specific additions — datasheet blocks, cross-reference links, drawing references, project parameters — handle the parts that ordinary markdown does not cover. You do not need to memorize all of it before you start. Read this page once, then use it as a lookup.

The markup is the same wherever you write a standard. What is expected of the writing is not, so this page keeps the two apart:

• The markup itself — everything up to and including the datasheet sections below. These are mechanics: break them and the document does not parse, render, or adopt correctly. They apply to every standard, wherever it lives.
• Editorial Guidelines for the Open Library — the last section. These govern standards published to the open SynC wiki, where SynC is the publisher and the library is meant to serve everyone in the industry equally.

If you are writing a standard for your own company, your personal library, or a single project, only the markup section applies. That standard is your document. You may name preferred manufacturers, carry an approved vendor list, encode your firm's house position, and organize it however your practice works — none of that is a defect in a standard written for your own use. The editorial section will still tell you why we do things a particular way in the open library, and some of it may be worth borrowing; none of it is required of you.

Every standard file follows the same skeleton:

---
title: Standard Title
category: Electrical
description: >
  When to use: ...
  Not intended for: ...
---

# Section Heading {toc}

## This note explains the requirement and why it matters. {note}

## The equipment shall meet the rating selected below.

```datasheet
label: Configurable Requirement
type: select
options:
  - Option A
  - Option B
default: Option A
```

## Routing shall coordinate with [[sync/raceways-and-conduit]], [[drawing: as indicated on the one-line diagram]].

Five elements make this work:

• Frontmatter at the top, for metadata
• Headings (#, ##, ###) for structure and element addressing — each one marked as a section ({toc}), a requirement clause (unmarked), or a note ({note})
• Narrative — written as clause and note headings rather than loose paragraphs, so every statement is individually addressable
• Datasheet blocks for configurable fields
• Cross-references and drawing references as inline links to other standards and to the contract documents

Each section below covers one of these in detail.

Every standard file begins with a YAML frontmatter block between two --- lines:

---
title: Grounding and Bonding for Electrical Systems
category: Electrical
description: >
  When to use: Grounding and bonding of low-voltage electrical systems...
  Not intended for: Lightning protection systems, medium-voltage substations...
---

• title — The displayed name of the standard. Sentence case, descriptive enough to read on its own outside the wiki nav.
• category — The library category (Electrical, Mechanical, Structural, etc.). Must match an existing category. When you save through the API, the standard's category is the one chosen when it was created (category_id), and the save ignores the frontmatter.
• description — A short two-line summary in When to use: / Not intended for: form. This is what a reader sees when deciding whether your standard is the right one for their project. Be specific about scope and exclusions.

Headings use standard markdown — # for level 1, ## for level 2, and so on. The system numbers headings automatically (1, 1.1, 1.1.1) based on nesting, so do not type numbers into the headings yourself.

# Scope
## General Requirements
### Soil Resistivity

Renders as:

1 Scope 1.1 General Requirements 1.1.1 Soil Resistivity

This is the most important principle of the markup. Each heading becomes one discrete element in the system — independently addressable (with a dotted address like 1.4.2), independently versioned, independently citable, independently commentable. Anything that is not a heading — a paragraph, a list, a table, a datasheet block — folds into the heading above it and is cited as part of that element.

That single fact drives the whole structure: if a requirement or a piece of rationale needs to be citable on its own, it has to be its own heading. A requirement buried inside a paragraph shares its parent's address and cannot be cited alone.

Every heading is one of three kinds, distinguished by a trailing marker:

• {toc} — Sections. Use it for the structural headings that organize the document: Scope, Referenced Standards, Submittals, Quality Assurance, Installation, Testing, Warranty, and their groupings. These are the headings a reader navigates by, and the only ones that appear in the table of contents. {toc} is about navigation only — a heading does not need it merely because it owns a list or datasheet.
• No marker — Requirement clauses. A requirement is left unmarked. It renders as a numbered clause with its address in the left gutter, so the gutter becomes a clean column of obligation numbers. The requirement sentence itself is the heading text: ### Deck shall be galvanized to ASTM A653 G90 minimum.
• {note} — Notes. Any narrative that is not an obligation — a scope statement, a definition, a "this section covers...", a rationale, a consequence — becomes a note. It renders as ordinary prose with its address trailing in parentheses, so it reads as explanation rather than a numbered demand. A note must never contain a shall/should/may requirement; if it does, that requirement belongs in its own clause.

If both markers somehow land on one heading, {toc} wins.

The consequence of "the heading is the element" is that a bare paragraph sitting under a heading has no address of its own. It carries citable meaning but cannot be cited, commented on, or revision-tracked — and under a clause it renders as an orphaned block of text. This is the one defect the convention exists to eliminate.

So every narrative sentence becomes its own heading:

• An obligation (shall / should / may) becomes a requirement clause (unmarked).
• Everything else — description, definition, rationale — becomes a {note}.

The only things that legitimately live as non-heading body are tables, datasheet blocks, and bullet lists. Each attaches to the heading directly above it and is cited as part of that element. That owning heading can be a section, a clause, or a note — for example, a clause that introduces a list owns it: ### The Contractor shall submit the following: followed by the bullet list and a checkbox datasheet, all cited as that clause.

Before — a compound clause with a paragraph floating under it, hiding two more requirements and a definition:

## Aesthetic Reveals {toc}
### Aesthetic reveals shall be formed in the insulation, fully back-wrapped and reinforced with base coat and mesh on all faces, and shall not reduce the insulation below the minimum thickness.
Reveals are decorative grooves cut into the EPS ... the sides and bottom shall be base-coated, meshed, and finished exactly like the field, never left as bare foam.

After — the definition is an addressable note, each obligation is its own clause, and nothing dangles:

## Aesthetic Reveals {toc}

### Reveals are decorative grooves routed into the EPS to articulate the facade; their sides and bottom are wall surface, not a free edge. {note}
### Aesthetic reveals shall be formed in the insulation and shall be fully back-wrapped.
### Reveals shall be reinforced with base coat and mesh on all faces of the groove.
### The sides and bottom of the reveal shall be base-coated, meshed, and finished exactly like the field, and shall never be left as bare foam.
### Reveals shall not reduce the insulation below the system's minimum thickness.

A clause should capture exactly one independent obligation — one normative verb-phrase, one subject. Split a compound sentence ("X and Y, and shall not Z") into one clause each where the parts are independently testable, and lift any requirement embedded in a paragraph out into its own clause. But keep an enumerated list that serves a single obligation together: "...identified by designation, profile, gauge, finish, and quantity" is one requirement — do not explode the field list.

When you are deciding between one long section and several shorter headings, lean toward more. Granularity is what makes a standard useful for project review, comment, and compliance tracking.

Do not skip levels. A heading may go only one level deeper than the one before it (# → ## → ###); jumping from # straight to ### is a parser error. Going shallower by any amount is fine. The limit is six levels (######). Don't go deeper.

The marker convention above is the current standard, but older standards predate it, so one rule reconciles the two:

• A document that uses zero {toc} markers is treated as legacy: every heading renders as a header.
• As soon as a document uses one {toc} marker, it opts into the convention: every unmarked heading now renders as a clause. So a document using the convention must mark all of its real sections with {toc} — otherwise a section you left unmarked will render as a clause by mistake.

Do not add a toc_depth key to frontmatter. It was the old way of capping the table of contents by heading level, and the {toc} marker replaced it — the marker decides what is a section, so there is nothing left for a depth cap to do. Nothing reads the key. If you are editing an older standard that still carries one, delete the line.

Narrative carries the specification language itself, and it is the bulk of a good standard: roughly 60 to 70 percent of the content. Under the element model above, narrative is not written as loose paragraphs. Each statement lives in its own heading (a requirement clause for an obligation, a {note} for description or rationale), so every statement can be addressed on its own. In the body under a heading, ordinary markdown works as you would expect: lists, bold, italic, inline code, blockquotes, and GFM pipe tables. Keep heading text plain. The public wiki shows bold, italic and code marks in a heading as literal characters.

The one formatting rule specific to SynC is no hard line wrapping: write each paragraph or heading as one continuous line in the source, and let the editor and renderer soft-wrap to whatever width the reader's window has. Hard-wrapping the source at 80 columns creates jagged text when the window is wider or narrower.

The narrative is binding specification language. SynC follows the construction industry's standard auxiliary verbs:

• shall — a mandatory requirement
• should — a strong recommendation; deviation requires justification
• may — optional, at the specifier's discretion

Write in active voice, directed at the responsible party ("the Contractor shall...", "the Engineer shall confirm..."). Keep it manufacturer-agnostic — no brand names, no model numbers, no "or approved equal."

To link to another standard in the same library, use the double-bracket wiki-link syntax:

Coordinate raceway routing with [[sync/raceways-and-conduit]] and conductor selection
with [[sync/conductors-and-cables]].

The format is [[sync/the-slug]]. Only sync/ links resolve; any other prefix renders as an unresolved reference. The link text is the slug in title case ([[sync/raceways-and-conduit]] reads "Raceways And Conduit"). To choose the text yourself, add it after a bar: [[sync/raceways-and-conduit|raceway standard]].

To cite one clause, name the adopted revision and then the clause address: [[sync/raceways-and-conduit@7#4.2.1]]. The revision is required. [[sync/raceways-and-conduit#4.2.1]] is not a valid citation and renders as plain text.

It is fine to link to a standard that does not exist yet. Dangling references are how the library grows: each one is a signal to the next contributor about what is missing.

Construction specifications routinely contain values that are determined by the project, not by the standard — quantities, dimensions, locations, ratings, schedules. The markup has two ways to mark these, and one decision rule picks between them.

The decision rule: if the value could ever be answered with a concrete selection, make it a datasheet field. A field gives the project engineer both exits — pick a value, or defer it to the drawings — so any "either the drawings or a selection" item belongs in a datasheet block (covered in the next section). The inline [[drawing: ...]] tag is reserved for things that can never be a field: locations, routing, extents, arrangements, and details that only a drawing can express.

Marking deferrals this way is what lets a project roll every drawing-determined value, across every standard it uses, into one drawing coordination checklist — the list the project team works to zero before each issue date.

When a requirement clause defers a value to the drawings, mark the deferral inline, inside the clause it serves:

### Switchgear location and arrangement shall be [[drawing: per the equipment room layout drawings]].
### Mounting height shall be [[drawing: per the mounting detail on the drawings]].
### Frost depth shall be [[drawing: as indicated on the civil drawings or determined from the local building code]].

Three rules keep the tags useful:

• The tag text is a locator only. It tells the reader where to look — "as indicated on the one-line diagram", "per the mounting detail". The clause heading already states what must be defined, so never restate the requirement inside the tag. Naming a fallback source is fine ("or determined from the local building code").
• One tag per item. Never bundle several independent drawing-determined items into one tag — each deserves its own clause and its own tag, just as each independent obligation deserves its own clause.
• The tag lives inside the requirement clause it serves, so each deferral belongs to exactly one addressable element.

Every datasheet field can be deferred by the project engineer — "as indicated on the drawings" is always available as a field state, stored alongside the value rather than as one of the options. The author's job is only to mark the fields where deferral is the expected answer, using drawing_ref:

```datasheet
label: Main Bus Continuous Current
type: range
unit: A
drawing_ref: "one-line diagram"
options:
  min: 800
  max: 5000
  setpoints: [800, 1200, 1600, 2000, 2500, 3000, 4000, 5000]
default: 1600
```

• drawing_ref: true marks the field as commonly drawing-determined and gives it a prominent "per drawings" toggle.
• drawing_ref: "<locator>" (preferred) additionally names where the value will be found — "one-line diagram", "head anchor detail" — and pre-labels the deferral.
• default: deferred starts the field in the deferred state on a new project, so the engineer opts out by choosing a concrete value. It is only valid alongside drawing_ref (the parser rejects it otherwise), and only worth using when most projects will defer; where they would not, choose between default: manufacturer, a concrete default, and no default at all by asking where the engineer would look for the value. The sentinel is a starting state, not a value — it is never stored as the field's default.

Two hard rules:

• A deferral is never an option. Do not add "Per drawings", "See schedule", or similar to options:. Deferral is a field state, stored alongside the value; written as an option it is indistinguishable from a real selection and it drops out of the coordination checklist. A field that is always drawing-driven is type: text with drawing_ref: and default: deferred — not a radio whose only option is "Per drawings".
• [[drawing: ...]] markup never goes inside a datasheet block — not in options, not in defaults, not in labels. Inline markup does not render inside datasheet YAML, so readers would see the literal brackets. The deferral belongs in drawing_ref, not in the values. Saving a standard with [[drawing: inside datasheet YAML is rejected.

Some values are not deferred to anyone — the manufacturer's standard offering is simply acceptable and no project decision is expected. Transformer impedance and standard enclosure finishes are the usual examples. default: manufacturer starts the field in that state:

```datasheet
label: Enclosure Finish
type: radio
options:
  - ANSI 61 gray
  - White
  - Custom color
default: manufacturer
```

• No drawing_ref — nothing is being coordinated, so there is nothing to point at.
• Use it on option types (radio, select). A numeric range wants a number; express the same idea there as no default plus a clause requiring the manufacturer to report the as-designed value in submittals.
• Like deferred, this is a field state, not a value. Do not also write "Manufacturer's standard" as an option string — that gives the same idea two competing representations.

A value is derived when it is objectively determinable from inputs already specified. It is not a free choice the catalog settles (manufacturer), and not something another document carries (drawing_ref) — whoever does the arithmetic, the same inputs yield the same answer. The archetype: the specifier states 4.16 kV and a 10,000 ft site, and the basic impulse level follows from published de-rating factors.

```datasheet
label: Basic Impulse Level (BIL)
type: select
derived: "system voltage and [[parameter: altitude]]"
options:
  - 60 kV
  - 75 kV
  - 95 kV
default: derived
```

• derived: "<basis>" names, in your own words, what the value follows from. It is a short pointer, not a restatement of the criteria — those belong in the owning clause. Write it so a competent bidder can execute without having to ask anyone.
• default: derived starts the field in the derived state; the engineer opts out by picking a concrete value.
• A field cannot be both derived and drawing_ref. A value follows from a stated basis or it lives in another document — not both.
• Bare derived: true is accepted where the adjacent clause states the derivation in full, but naming the basis is better: the pill then reads "DERIVED — from system voltage and site altitude (10,000 ft)" instead of leaving the reader to hunt for it.

Derivation is also the clean fix for a common conflict: when the owning clause explains how a value is arrived at ("leakage class shall be selected based on operating pressure and energy classification") while the field offers a free selection, the document is telling the reader two different things. Adding derived: with the basis the clause already states resolves it without deleting the field or rewriting the clause.

Some facts belong to the project rather than to any one standard: the site altitude, the seismic design category, the outdoor design temperature. Asking each of them as a datasheet field inside every standard that needs one gives a project a dozen copies of the same question, with nothing keeping the answers consistent.

Instead, write the fact into the sentence that needs it:

## Equipment shall be de-rated for [[parameter: altitude]] in accordance with the manufacturer's published correction factors.

In a project context the reference renders with the answer substituted — "de-rated for the site altitude of 10,000 ft". Unanswered, it renders as a visible TBD, which is the right behavior even in an issued PDF: a missing project fact should look missing rather than quietly reading as complete.

Writing the reference is the entire action. There is nothing to declare, register, or set up first — the platform derives the rest from the references themselves.

Both parts have to be true:

1. The fact is defined outside the scope of any particular standard.
2. There is exactly one true answer per project, whichever standard asks.

altitude, seismic-design-category, and exposure-category pass. System voltage fails — it is selected within the electrical standards, and a real project runs 480 V, 4.16 kV, and 120 V at once. Warranty period fails (it varies per product). Recurring in many standards is never sufficient on its own; apply the test.

An apparent failure is often one name doing two jobs. "Maximum ambient temperature" looks per-location until it is named precisely: the site's outdoor design condition has exactly one answer per site, while a particular conditioned room's ambient is a different fact that stays a datasheet field. Try the precise name before ruling a candidate out.

• Syntax is [[parameter: name]] — a peer of [[drawing:]]. Never [[parameter/name]]; the slash form reads as a citation and will not resolve.
• Names are bare, scope-free, lower-case with hyphens. altitude, never project-altitude or electrical-altitude. A scope qualifier breaks every reference the day scoped resolution arrives. Precision about which physical fact is not scoping — site-ambient-temperature-maximum is a good name.
• Check the spelling against names already in use. A typo does not fail; it silently mints a second parameter the project then has to answer twice. When you use a name the library has not seen, you will be asked to describe it — write that description for the specifier who will answer the question later, and state the expected unit in prose ("the site elevation above sea level, in feet"). If an existing name's description is not what you mean, pick a different name rather than overloading it.
• Valid in clause prose and inside a derived: basis. Nowhere else in datasheet YAML — a parameter marker placed in an option or a label is never indexed, so the reference silently does nothing.

Consequences point at their cause. Whether seismic bracing is required is not an independent fact — it follows from the seismic design category. Make the cause the parameter, and mark the consequence as a derived field: derived: "[[parameter: seismic-design-category]]". That way the document cannot contradict itself.

A datasheet block defines a configurable field — a place where the specifier picks an option, selects a value, or enters a project-specific input. Datasheet blocks are what turn a standard from a static document into a configurable specification: the same standard adapts to one project's 480 V service and another's 208 V service by selecting an option rather than rewriting the section.

A block is opened with ```datasheet, closed with ```, and contains YAML between the delimiters:

```datasheet
label: Voltage Rating
type: range
unit: V
options:
  min: 208
  max: 600
  setpoints: [208, 240, 480, 600]
```

A datasheet block attaches to the nearest heading above it; that attachment is how the system knows where the field belongs in the standard's structure. A bullet list or a table may sit between the heading and the block, so a clause can introduce a list and then ask which items the project needs. One heading may own several blocks. Give each block under the same heading its own label.

Any other key is an error, so a misspelled key is caught rather than ignored.

The company and project standard editor includes a Markup Language Reference with form previews for every type. The summary below is the quick written lookup.

Use only when no controlled input fits. Most fields in most standards should be one of the structured types below.

```datasheet
label: Special Field Conditions
type: text
options:
  multiline: true
```

Add multiline: true for a textarea instead of a single-line input.

Use when the specifier picks exactly one option from a small set (typically 2–5) and seeing all options at once is helpful.

```datasheet
label: Equipment Grounding Conductor Material
type: radio
options:
  - Copper
  - Aluminum or copper-clad aluminum
default: Copper
```

Use when one option is selected from a list that would crowd the page if shown all at once. Renders as a dropdown.

```datasheet
label: Enclosure Type
type: select
options:
  - Type 1
  - Type 3R
  - Type 4
  - Type 4X
  - Type 12
default: Type 1
```

Use when the specifier may select any combination from a small set.

```datasheet
label: Metallic Systems to be Bonded
type: checkbox
options:
  - Metal water piping system
  - Metal gas piping (interior)
  - Structural building steel
  - Metal HVAC duct systems
default:
  - Metal water piping system
```

Like checkbox, but rendered as a dropdown — use for longer lists (roughly 5 or more options) where displaying all of them inline would crowd the page.

Use for any numeric requirement. Specify min and max, then either step (uniform increments) or setpoints (specific allowed values) — one or the other, not both. When setpoints are present the slider snaps to them and any step you wrote is ignored, so writing both only hides one of them.

```datasheet
label: Maximum Acceptable Ground Resistance
type: range
unit: Ω
options:
  min: 1
  max: 25
  setpoints: [1, 3, 5, 10, 25]
default: 5
```

Use setpoints for requirements that follow standard industry values (amperages, voltages, conduit sizes). Use step for genuinely continuous values where any multiple of the step is valid.

Two constraints on a range worth knowing before you hit them:

• Setpoints must be plain numbers. The slider does arithmetic on them to snap to the nearest one, so - 400 (standard) will not work. Put that kind of gloss in the owning clause or a {note}.
• default has to be a value the field can reach — inside min/max, and either one of the setpoints or an exact multiple of step counting up from min. A default of 240 on a field stepping by 25 from 0 is off-grid and will fail adoption.

constraint says which way a value binds, and the page states it in words:

```datasheet
label: Short-Circuit Current Rating
type: range
unit: kA
options:
  min: 10
  max: 200
  setpoints: [10, 14, 22, 25, 35, 42, 50, 65, 85, 100, 150, 200]
default: 65
constraint: min
```

This reads "Not less than 65 kA". Because the page supplies the direction, the label names only the quantity: "Short-Circuit Current Rating", not "Minimum Short-Circuit Current Rating". Leave constraint out and a range reads as exact, a checkbox or listbox as all of.

A range also implies an ordered axis: the slider puts min on the left, so it reads honestly only when the number grows with the quantity the label names. Scales that run backwards — AWG and sheet gauge, where a larger number is a smaller conductor — belong in a select, since dragging right on "Minimum Conductor Size" must not quietly mean smaller wire.

By default, the option label and the stored value are the same string. When you need them to differ — typically when storing a short code — use a YAML mapping in place of a list:

```datasheet
label: Installation Method
type: radio
options:
  Surface Mounted: surface
  Flush Mounted: flush
  Free Standing: freestanding
default: surface
```

The specifier sees "Surface Mounted"; the system stores surface.

Nothing in this section is enforced — these are two habits that make a datasheet easier to reuse across projects, with the reasoning attached so you can judge whether they suit your library.

One field, one decision. A field that captures exactly one independent choice stays small and answerable. When options bundle two unrelated decisions ("Copper, 600 V" vs. "Aluminum, 1000 V"), the list has to grow by multiplication to cover the real combinations, and afterwards nobody can query the two decisions separately — the combination is stored as one opaque string.

Decide a default by asking where the answer lives. One question settles most fields: where would the engineer look for this value?

Leaving default out is a real answer, not an omission. An empty field asks the question; a guessed one answers it wrongly and silently.

Project-sized quantities — kVA, amps, voltage, dimensions, counts — are the ones worth watching. Two failure modes cost differently: defaulting to the most conservative option (highest rating, most stringent test, most expensive material) produces specifications nobody uses as written, which reviewers usually catch. Defaulting to a plausible-sounding project quantity produces a specification that is quietly wrong for every project that accepts it, and that one tends to survive review — because it looks finished.

The parser checks the standard as you save and surfaces errors inline. The most common ones to watch for:

• Datasheet block before any heading — every datasheet block must follow a heading, because that is how it gets attached to a section.
• Missing label or type — every datasheet block requires both.
• Empty options on a choice type — radio, select, checkbox, and listbox all need at least one option.
• range missing min/max, or neither step nor setpoints — specify the bounds and one stepping strategy.
• Heading level skipped — a ### must follow a ##, not jump from a #.
• Unclosed datasheet block — every ```datasheet must have a closing ```.
• default: deferred with no drawing_ref — a deferral with no destination tells the reader nothing about where to look.
• [[drawing: ...]] inside datasheet YAML — it does not render there; use drawing_ref instead.
• A field marked both derived and drawing_ref — a value follows from a stated basis or lives in another document, not both.

A save with any of these errors is refused. The editor lists each one with its line number so you can fix it and save again.

Standards published to the open wiki are additionally checked against the editorial rules in the next section, and some of those do block publishing there. A standard in your own company, personal, or project library is not subject to them.

This section applies to standards published to the open SynC wiki. It does not apply to standards in your company library, your personal library, or a single project — see the note at the top of this page. Everything above this line is the markup and applies everywhere.

The open library is published by SynC and is meant to be usable by everyone in the industry — competitors included, on opposite sides of the same bid. That is a different job from writing a standard for your own firm, and it comes with obligations that a private standard has no reason to carry.

A wiki standard is a general template. Specificity enters when a project fills out the datasheet — not when we write the template. Between alternatives that are code-legal and commercially available, the template does not take sides.

This is an ethical constraint before it is an editorial one. An open library that quietly steered every reader toward one manufacturer's configuration would be using a public resource to pick winners, and it would deserve to lose the trust that makes it worth reading.

• A selecting field spans the full decision space real projects use, including choices the author would not personally recommend. If code permits it and the market sells it, it is selectable. Leaving an option out to steer the choice is the defect — a recommendation is expressed through the default and through explanatory notes, never through omission.
• A range bound is an option in disguise. A min sitting above a code-legal configuration silently forbids it, exactly like a missing radio option. Pick bounds that span the real product range, and let a clause or note explain the tradeoff.
• Editorial prohibitions are written conditionally. A "shall not" that reflects the author's preference rather than code or physics must yield to the datasheet: "Unless the datasheet policy permits X, X shall not be used for ...". Only code-mandated or physically-wrong configurations get unconditional bans.
• Notes state facts, mechanisms, and condition-tied tradeoffs — never verdicts. "Copper is the appropriate choice for commercial construction" assumes the reader's project type and decides for them. "Thermoset insulation does not soften under sustained heat, so it is preferred where sustained heat exists" ties the recommendation to a condition the engineer can check.
• Do not remove an option just because a clause forbids it. If the standard's text makes an offered option unselectable, make the clause conditional rather than deleting the reader's ability to specify it. Values that are an engineering error in every project are a different matter and stay out.

No brand names, no model numbers, no "or equal" — describe the performance requirement and let the project's customization layer add approved manufacturers if it wants to. "Or equal" is not a workaround: naming a product still anchors the specification to that manufacturer.

An option list that maps perfectly onto one manufacturer's catalog while excluding valid competitor configurations is not agnostic either, even with no brand name in sight.

A heading is not a divider. It is an addressable element, and for search it is the single context slot every clause beneath it inherits — so a heading that names no subject costs twice: it puts an empty row in the table of contents, and it shadows the informative heading above it for every clause underneath.

Avoid bare structural words as a whole heading: General, General Requirements, Materials, Application, Execution, Products, Requirements, Performance, Construction, Components, Sizing, Purpose, Access, Summary, Description, Overview, Introduction, Notes, Miscellaneous, Other. (# Scope is the one exemption — it is the document's own opening.) These are also conventional article names from proprietary specification systems, which the copyright rules keep us away from as organizational structure.

The fix is usually to delete the level and promote its children, not to rename it — the parent already names the subject:

# Water Hammer Arrestors {toc}
## Arrestors shall conform to PDI WH-201 ...

Qualified names are fine; the ban is on the bare word. Materials and Mix Design, Panel Construction, and Reader Mounting all name a subject. And no two headings in one document should read the same — two headings reading "General Requirements" are two elements, neither of which can be cited or compared.

The list of referenced standards is a bibliography, not narrative and not a list of obligations. Render it as a markdown table that is body of the # Referenced Standards {toc} section:

# Referenced Standards {toc}
## Equipment, materials, and installation shall comply with the latest adopted edition of each of the following unless a specific edition is cited.
## Where referenced standards conflict, the more stringent requirement shall govern unless the Engineer of Record directs otherwise in writing.

| Standard | Title |
|----------|-------|
| NFPA 99 | Health Care Facilities Code |
| ASTM B819 | Seamless Copper Tube for Medical Gas Systems |

Do not give each referenced standard its own {note} or its own shall clause — a bibliography is not a list of obligations, and doing so inflates the requirement count. The two introductory sentences do stay as their own headings; only the list itself is the table.

The open library uses real notation rather than ASCII substitutes: write °C not degC, ≤ not <=, ± not +/-, Ω not ohm, µ not micro. For phase and diameter, Φ, Ø and ⌀ are all accepted.

The open library does not accept typographic punctuation: use straight quotes rather than curly ones (U+2018, U+2019, U+201C, U+201D), and three periods rather than the single-character ellipsis (U+2026). This applies inside datasheet YAML too, in labels, options, and unit:. A company, personal or project library accepts both.

A standard's job is to be cited in a contract without starting a dispute. These are the recurring dispute generators, and they are the author's responsibility — no automated check catches them:

• Define the trigger. No open-ended "as required / as necessary / promptly / at all times". Tie the obligation to a milestone, a measurable condition, or a datasheet value.
• Give every subjective term an arbiter or a number. "Adequate", "suitable", "proper", "good workmanship", "defective" each need a measurable criterion, or an explicit deferral to the Architect or Engineer of Record.
• Assign responsibility and cost. Re-test cost after a failure, repair cost, and damage during a warranty repair are the classic unassigned-cost fights. Do not leave a passive "shall be tested" with no actor.
• Add the carve-out. A blanket requirement needs its real exceptions stated. "Restore equal to or better than existing" is unenforceable without also requiring a documented pre-existing-condition baseline.
• State one governing rule per topic. If the same obligation appears in three sections with different wording, a contractor will play the narrowest against the rest.

Content must be independently created from public sources only: consensus standards (ASTM, ANSI, IEEE, UL, NEMA, NFPA, NEC, IBC, ACI, ASHRAE), public-domain government guide specifications (UFGS, VA, USACE), building codes, manufacturer technical data mined for facts and rewritten agnostically, professional knowledge, and existing CC BY-SA SynC standards.

Never copy, paraphrase, or adapt prose from a proprietary specification system or from a manufacturer's guide-form specification — mine those for facts only, never as a template or as an AI prompt input. Never use proprietary section or division numbering as organizational structure.

Do not add an in-body license, authorship, or copyright footer. Licensing is library-wide and stated on the contributing page; authorship is tracked by page history.

• The Markup Language Reference in the company and project standard editor shows a form preview for each datasheet field type.
• The Converting your specifications help page (/help/converting-specifications) covers turning the specifications you already use into SynC standards, with a prompt for an AI assistant.
• Contributing to SynC StandardsResolves to the current adopted revision.about/contributing-to-sync-standards covers attribution, licensing, and the contribution process.
• Why SynC Standards ExistsResolves to the current adopted revision.about/why-sync-standards explains why an open library of structured standards is worth building in the first place.

The library grows one contribution at a time. The markup is just the keyboard for it.