Circuit Genome Export Standard (CGES)

Circuit Genome Export Standard (CGES)

Version Map

Implementers MUST use metadata.core_contract_version and metadata.profile_id for payload validation behavior. Document version metadata MUST NOT be used to infer payload validity.

1. Purpose

This standard defines a transport-neutral export contract for schematic design semantics so data remains portable across CAD tools and reusable by Circuit Genome and compatible downstream systems.

This document defines two transport profiles and one interoperability contract:

An exporter may claim conformance to either profile independently or to both. For interoperability between independent implementations, CGES-CORE-1.0 is the normative baseline.

A JSON exporter claiming cross-team interoperability MUST claim both CGES-JSON-1.0 and CGES-CORE-1.0. Consumers SHOULD treat CGES-JSON-1.0 without CGES-CORE-1.0 as schema-shaped JSON, not guaranteed interoperable JSON.

1.1 Implementation Effort Levels (Informative Maturity Labels)

CGES may also be described using effort tiers. These tiers are informative maturity labels for exporter completeness, not independent conformance claims.

2. Definitions and Acronyms

The following definitions apply to this standard:

3. Normative Language

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119/8174.

4. Source Context and Identity

4.1 Source Requirements

4.2 Identity Attributes (Exemplar)

Identity MAY be derived from schematic parts, for example:

The PCB1 and DWG1 names in this section are informative source-side examples, not required identifiers.

4.3 Defaulting Rules

4.4 Multi-Board Identity (Backward-Compatible Extension)

4.5 Tool Implementation Guides (Informative)

Tool-specific extraction and parameter-mapping behavior is informative and maintained outside this core standard body.

Core profile conformance MUST be evaluated against this standard's profile requirements, not guide-specific implementation details.

4.6 Deterministic Identity Conflict Resolution (Normative)

Exporters MUST apply deterministic rules when multiple identity candidates exist or required identity values are missing.

4.7 Analysis Module Bundles (Normative Extension Pattern)

Base CGES compliance is intentionally lightweight. For interoperability, rich analysis payloads use one canonical location.

5. Shared Extraction Rules

5.1 Excluded Utility or Non-Design Parts

The following prefixes represent utility symbols or non-electrical placeholders and are excluded in profile-specific contexts:

5.2 Test Point Identification

5.3 Pin Resolution

When resolving a pin identifier from a pin reference:

1. Exporter SHOULD use a canonical compiled or instantiated pin designator when the source CAD connectivity model exposes one.
2. If no compiled pin designator exists, exporter SHOULD use the source pin number or source pin designator field.
3. If no source pin number/designator exists, exporter SHOULD extract a deterministic numeric token from the instance gate name when that encoding is known to represent connector position.
4. If no numeric token is resolved, exporter SHOULD fall back to the source pin name.
5. Exporter MAY emit an empty pin string only when the source data has no deterministic pin identifier and the same unresolved value is used consistently everywhere that pin is referenced.

5.4 CAD Tool Variability and Field Mapping

6. Conformance Profile: CGES-JSON-1.0 (Core Contract: CGES-CORE-1.0)

CGES-CORE-1.0 is the interoperability baseline for this profile and covers identity, metadata, components, nets, and encoding rules.

For cross-team JSON interchange, exporters SHOULD treat the combined claim CGES-JSON-1.0 + CGES-CORE-1.0 as the default publishable contract.

6.1 File Naming

Recommended export filename:

{BOARD_PN}_{BOARD_REV}_CGES.json

For filename purposes, BOARD_REV refers to identity.board_rev, not metadata.schematic_revision.

Exporters SHOULD use the recommended filename format. Conformance MUST be determined from in-file metadata and payload content.

6.2 Top-Level Structure

A compliant document MUST be a JSON object with at least these top-level keys:

The document MAY include:

Version signaling rules:

6.3 identity Object

identity MUST include:

6.4 metadata Object

metadata MUST include:

identity.board_rev is authoritative for board identity.

metadata.schematic_revision carries source-document revision context and MAY differ from identity.board_rev when schematic/document control is independent of board identity control.

If deprecated metadata.revision is emitted for backward compatibility, it MUST equal metadata.schematic_revision and consumers SHOULD treat schematic_revision as authoritative.

metadata MAY include:

Extension declaration rules:

6.5 components Array

Each component object MUST include:

Each pins entry MUST include:

Within a board scope, each emitted refdes MUST be unique.

Components with excluded prefixes (Section 5.1 common set) MUST NOT be emitted.

Module-specific fields are optional for base CGES and MUST be grouped under analysis_modules on each component when present.

Placeholder values such as unspecified satisfy the non-empty syntax requirement for role and function, but validators and downstream consumers SHOULD treat them as incomplete semantics and report quality warnings.

analysis_modules MAY include:

For backward compatibility during transition, exporters MAY also emit legacy flat keys such as tolerance, v_rating, i_rating, and p_rating; these keys are non-canonical and MUST NOT override analysis_modules.

Legacy flat keys and alias-derived keys are accepted in the current contract, SHOULD trigger quality warnings in future minor-version validator updates, and SHOULD be removed from conformance claims in the next major core-contract revision.

Human-readable extension references and canonical field names are maintained in docs/reference/epsa-extension.html, docs/reference/fmea-extension.html, and docs/reference/wcca-extension.html.

6.6 nets Array

Each net object MUST include:

Each connections entry MUST include:

Connections referencing excluded prefixes (Section 5.1 common set) MUST NOT be emitted.

Referential integrity rules:

6.7 Optional test_integration Object

If present, test_integration MUST include:

Each test_points entry MUST include:

6.8 Optional analysis Object

If present, analysis MUST include:

analysis MAY include:

Derived-count consistency rules:

6.9 Encoding and Escaping

6.10 additional_boards Extension (CGES-JSON-MULTIBOARD-1.0)

The optional additional_boards key enables multiple boards and drawings in a single CGES JSON document while preserving legacy compatibility.

Rules:

7. Conformance Profile: CGES-MD-1.0

CGES-MD-1.0 is a human-readable reporting profile. It is not the canonical machine-consumable interchange contract and SHOULD NOT be used as the primary data source when a compliant JSON payload is available.

7.1 File Naming

Preferred filename:

{BOARD_PN}_{BOARD_REV}_CGES.md

For filename purposes, BOARD_REV refers to identity.board_rev, not metadata.schematic_revision.

If identity attributes are missing, exporter MAY derive the stem from the design filename.

7.2 Required Document Header

A compliant Markdown export MUST begin with:

7.3 Required Sections

A compliant Markdown export MUST include the following sections in order:

1. # Circuit Identification
2. # Netlist
3. # Partlist
4. # Pinout Description Table, P1 (or an explicit "not found" note)

7.4 Circuit Identification Section

This section MUST provide a Markdown table with these fields:

7.5 Netlist Section

The netlist table MUST use columns:

Rules:

7.6 Partlist Section

The partlist table MUST use core columns:

When EPSA module data (or transitional legacy equivalents) is available, exporter MAY append module columns:

Excluded prefixes MUST follow Section 5.1 Markdown-partlist exclusions.

For markdown partlist output:

PART TYPE SHOULD be derived using the reference longest-prefix-first classifier maintained in docs/reference/part-type-classifier.html.

For core conformance, exporters MAY emit PART TYPE as OTHER when no deterministic local classifier is implemented.

7.7 Pinout Section (P1)

The pinout section MUST enumerate P1 attributes where key starts with pin (case-insensitive) and emit:

If no P1 part exists, exporter MUST emit an explicit note.

7.8 Markdown Escaping

Exporter MUST escape vertical bars (|) in cell values.

8. API Transport Compatibility

This standard is transport-neutral and API-ready.

9. Manufacturing Mapping (Informative, Moved Out of Core)

Panelization and pieces-per-panel logic is outside core CGES interoperability and is maintained in:

Exporters MAY include manufacturing-derived metadata through extension keys, but such data MUST NOT affect core profile conformance.

10. Compliance Declaration

An exporter may declare compliance using one of:

For cross-team JSON interoperability claims, exporters MUST declare both CGES-JSON-1.0 and CGES-CORE-1.0.

Exporter compliance declarations MUST include profile, source tool, and exporter version. Effort tier MAY be included as an informative maturity label.

Consumer capability statements MAY omit effort tier.

Recommended extended exporter declaration format:

{PROFILE} / {EFFORT_TIER} / {SOURCE_TOOL} / {EXPORTER_VERSION}

When effort tier is omitted, {PROFILE} / {SOURCE_TOOL} / {EXPORTER_VERSION} is also valid.

When included, EFFORT_TIER MUST be one of minimum, moderate, or maximum.

Compliance requires satisfying all MUST statements in the relevant profile(s).

11. Change Control

12. Conformance Artifacts (Normative)

To reduce implementation ambiguity, this standard requires machine-checkable conformance artifacts.

13. Altium Mapping Annex (Informative)

This annex has been moved to the tool implementation guide to keep the core standard transport-focused.

The guide is informative and MUST NOT override profile-level MUST requirements in this document.