Skip to main content

ADR-002 - Code Format Convention

  • Status: Accepted
  • Decision Date: 2025-05-28
  • Deciders: PIES Design Team
  • Category: Data Model, Ontology

Context​

PIES relies on controlled vocabularies and enumerated code values to classify assets, relationships, and message kinds. Without a standardized format for these codes, implementations across agencies and downstream systems risk inconsistency, validation failures, and incompatibility. Field consultation with subject matter experts indicated that uppercase conventions are prevalent in the natural resource permitting domain due to Oracle database precedent and existing government systems. Establishing an explicit, documented standard ensures that all code values are uniform from inception and remain maintainable across the ecosystem.

Decision​

Adopt SCREAMING_SNAKE_CASE as the canonical format for all code values and controlled vocabulary enumerations in PIES. This applies to all fields with enumerated domains, including but not limited to asset_kind (formerly record_kind; see ADR-007) and message kind (RECORD). All code values shall be uppercase with words separated by underscores. No lowercase variants or alternative formats are permitted.

Rationale​

SCREAMING_SNAKE_CASE is visually distinct and immediately recognizable as a controlled value, reducing implementation errors and improving code reviews. The uppercase convention aligns with Oracle database standards and existing government systems that already use this format, minimizing friction for agencies integrating with PIES. Consistency across all code values simplifies validation logic, schema generation, and downstream system integration. Establishing this standard early prevents the proliferation of inconsistent formats and the technical debt that would result from supporting multiple variants.

Assumptions​

  • All current and future controlled vocabularies will be representable in SCREAMING_SNAKE_CASE format.
  • Validators and schema tools will enforce strict adherence to this format.
  • Code value is case-sensitive and always uppercase when transmitted in messages.
  • Agencies and downstream systems can adopt this convention without breaking existing integrations beyond the version boundary.

Options Considered​

  • Lowercase snake_case: More aligned with programming language conventions (Python, Rust). Rejected because it diverges from Oracle precedent and government system conventions already in use, creating barriers to adoption in the natural resource permitting domain.
  • camelCase or PascalCase: Common in JavaScript and JSON APIs. Rejected because it conflicts with existing government database standards and reduces visual distinctness of controlled values.
  • SCREAMING_SNAKE_CASE (chosen): Uppercase convention with underscore separators. Aligns with Oracle precedent, improves visual recognition, maintains consistency with existing domain systems.

Consequences​

Positive​

  • All code values are visually distinct and immediately recognizable as controlled vocabulary.
  • Validation is deterministic and case-sensitive, reducing implementation ambiguity.
  • Alignment with Oracle and existing government systems reduces adoption friction for agencies.
  • Schema and code generation tools can rely on a stable, recognizable format.
  • Single standard eliminates the maintenance burden of supporting multiple code formats.

Negative​

  • Breaking change to schemas if prior implementations used lowercase or alternative formats.
  • Some implementers may find uppercase less aesthetically pleasing than lowercase or mixed case.
  • Future code values must be carefully named to fit naturally into SCREAMING_SNAKE_CASE format. Complex multi-word concepts may result in long, awkward code values.
  • Migration effort required across all existing documentation, examples, and downstream systems to adopt the convention.

References​

  • Oracle Database SQL Style Guide: Uppercase identifiers are preferred in Oracle schemas and stored procedures.
  • Natural Resources Permitting Domain: Subject matter expert consultation confirmed uppercase predominance in existing BC government systems.

None at this time. Future ADRs on code values may reference this decision.