cispec — Change Item Attribution Standard on cispec

matrix_id.h — Canonical C99 Reference Header

Mon, 29 Jun 2026 00:00:00 +0000

matrix_id.h#

Single-header C99 reference implementation. Copy into your project’s include path. No build system integration required beyond #include "matrix_id.h".

Configure via preprocessor defines before inclusion:

cc -DCISPEC_ORGANIZATION='"daplanet"' \
 -DCISPEC_ORGUNIT='"dps"' \
 -DCISPEC_APPLICATION='"my-tool"' \
 -DCISPEC_VERSION='"1.0.0"' \
 -include matrix_id.h \
 main.c -o my-tool

Or define in a dedicated translation unit (matrix_id.c) that includes this header after setting the macros, and link normally.

Source#

/* SPDX-License-Identifier: BSD-2-Clause
 *
 * matrix_id.h — org.cispec Change Item attribution header
 * Canonical source: https://cispec.org/spec/matrix_id.h
 * Spec version: 1.0
 *
 * Bakes org.cispec.* attribution strings into compiled artefacts as
 * volatile const char[] arrays, extractable with strings(1) without
 * executing the binary.
 *
 * Required defines (set before inclusion or via -D flags):
 * CISPEC_ORGANIZATION — owning organisation slug
 * CISPEC_ORGUNIT — organisational unit slug
 * CISPEC_APPLICATION — application or service name
 * CISPEC_VERSION — semver 2.0 version string
 *
 * Optional defines:
 * CISPEC_OWNER — identity contact (key fingerprint or handle)
 * CISPEC_OID — IANA OID arc (default: iso.org.dod.internet.42387)
 * CISPEC_DUNS — D&B DUNS in OID notation
 * CISPEC_CUSTOMER — customer identifier
 * CISPEC_COSTCENTER — cost centre identifier
 * CISPEC_ROLE — functional role slug
 * CISPEC_ENVIRONMENT — deployment environment slug
 * CISPEC_SPECVERSION — cispec spec version validated against (default: "1.0")
 */

#ifndef MATRIX_ID_H
#define MATRIX_ID_H

/* ------------------------------------------------------------------ */
/* Required keys — compilation fails if any are absent */
/* ------------------------------------------------------------------ */

#ifndef CISPEC_ORGANIZATION
# error "matrix_id.h: CISPEC_ORGANIZATION must be defined"
#endif

#ifndef CISPEC_ORGUNIT
# error "matrix_id.h: CISPEC_ORGUNIT must be defined"
#endif

#ifndef CISPEC_APPLICATION
# error "matrix_id.h: CISPEC_APPLICATION must be defined"
#endif

#ifndef CISPEC_VERSION
# error "matrix_id.h: CISPEC_VERSION must be defined"
#endif

/* ------------------------------------------------------------------ */
/* Defaults for optional keys */
/* ------------------------------------------------------------------ */

#ifndef CISPEC_OID
# define CISPEC_OID "iso.org.dod.internet.42387"
#endif

#ifndef CISPEC_SPECVERSION
# define CISPEC_SPECVERSION "1.0"
#endif

/* ------------------------------------------------------------------ */
/* Attribution string array — volatile prevents dead-code elimination */
/* ------------------------------------------------------------------ */

volatile const char CISPEC_ID_ORGANIZATION[] =
 "org.cispec.organization=" CISPEC_ORGANIZATION;

volatile const char CISPEC_ID_ORGUNIT[] =
 "org.cispec.orgunit=" CISPEC_ORGUNIT;

volatile const char CISPEC_ID_APPLICATION[] =
 "org.cispec.application=" CISPEC_APPLICATION;

volatile const char CISPEC_ID_VERSION[] =
 "org.cispec.version=" CISPEC_VERSION;

volatile const char CISPEC_ID_OID[] =
 "org.cispec.oid=" CISPEC_OID;

volatile const char CISPEC_ID_SPECVERSION[] =
 "org.cispec.specversion=" CISPEC_SPECVERSION;

#ifdef CISPEC_OWNER
volatile const char CISPEC_ID_OWNER[] =
 "org.cispec.owner=" CISPEC_OWNER;
#endif

#ifdef CISPEC_DUNS
volatile const char CISPEC_ID_DUNS[] =
 "org.cispec.duns=" CISPEC_DUNS;
#endif

#ifdef CISPEC_CUSTOMER
volatile const char CISPEC_ID_CUSTOMER[] =
 "org.cispec.customer=" CISPEC_CUSTOMER;
#endif

#ifdef CISPEC_COSTCENTER
volatile const char CISPEC_ID_COSTCENTER[] =
 "org.cispec.costcenter=" CISPEC_COSTCENTER;
#endif

#ifdef CISPEC_ROLE
volatile const char CISPEC_ID_ROLE[] =
 "org.cispec.role=" CISPEC_ROLE;
#endif

#ifdef CISPEC_ENVIRONMENT
volatile const char CISPEC_ID_ENVIRONMENT[] =
 "org.cispec.environment=" CISPEC_ENVIRONMENT;
#endif

/* ------------------------------------------------------------------ */
/* Sentinel — marks end of org.cispec block in strings(1) output */
/* ------------------------------------------------------------------ */

volatile const char CISPEC_ID_SENTINEL[] =
 "org.cispec.specversion=" CISPEC_SPECVERSION;

#endif /* MATRIX_ID_H */

Verification#

After building, confirm the strings are present:

matrix-id.lisp — Canonical SBCL Reference Module

Mon, 29 Jun 2026 00:00:00 +0000

matrix-id.lisp#

SBCL Common Lisp reference module. Load before compiling your system to embed org.cispec.* attribution strings in the compiled image. The strings are defined as defconstant forms and survive save-lisp-and-die dumps.

Source#

;;;; SPDX-License-Identifier: BSD-2-Clause
;;;;
;;;; matrix-id.lisp — org.cispec Change Item attribution module
;;;; Canonical source: https://cispec.org/spec/matrix-id.lisp
;;;; Spec version: 1.0
;;;;
;;;; Embeds org.cispec.* attribution strings into a compiled SBCL image
;;;; as defconstant forms. Strings survive save-lisp-and-die dumps and
;;;; are present in the compiled fasl.
;;;;
;;;; Usage: load before compiling your system, or add to your .asd file
;;;; as a component with :depends-on ("matrix-id").
;;;;
;;;; Required parameters — set via environment or redefine before loading:
;;;; CISPEC_ORGANIZATION
;;;; CISPEC_ORGUNIT
;;;; CISPEC_APPLICATION
;;;; CISPEC_VERSION

(defpackage #:org.cispec.matrix-id
 (:use #:cl)
 (:export
 #:+organization+
 #:+orgunit+
 #:+owner+
 #:+oid+
 #:+duns+
 #:+customer+
 #:+costcenter+
 #:+application+
 #:+role+
 #:+version+
 #:+environment+
 #:+specversion+
 #:label-set
 #:verify-required))

(in-package #:org.cispec.matrix-id)

;;; ----------------------------------------------------------------
;;; Helper — read from environment with fallback
;;; ----------------------------------------------------------------

(defun env-or (var default)
 "Return the value of environment variable VAR, or DEFAULT if unset or empty."
 (let ((val (uiop:getenv var)))
 (if (and val (plusp (length val))) val default)))

;;; ----------------------------------------------------------------
;;; Required attribution constants
;;; ----------------------------------------------------------------

(defconstant +organization+
 (env-or "CISPEC_ORGANIZATION" "")
 "org.cispec.organization — owning organisation slug.")

(defconstant +orgunit+
 (env-or "CISPEC_ORGUNIT" "")
 "org.cispec.orgunit — organisational unit slug.")

(defconstant +application+
 (env-or "CISPEC_APPLICATION" "")
 "org.cispec.application — application or service name.")

(defconstant +version+
 (env-or "CISPEC_VERSION" "")
 "org.cispec.version — semver 2.0 version string.")

;;; ----------------------------------------------------------------
;;; Optional attribution constants
;;; ----------------------------------------------------------------

(defconstant +owner+
 (env-or "CISPEC_OWNER" "")
 "org.cispec.owner — identity contact (key fingerprint or handle).")

(defconstant +oid+
 (env-or "CISPEC_OID" "iso.org.dod.internet.42387")
 "org.cispec.oid — IANA OID arc.")

(defconstant +duns+
 (env-or "CISPEC_DUNS" "")
 "org.cispec.duns — D&B DUNS in OID notation.")

(defconstant +customer+
 (env-or "CISPEC_CUSTOMER" "")
 "org.cispec.customer — customer identifier.")

(defconstant +costcenter+
 (env-or "CISPEC_COSTCENTER" "")
 "org.cispec.costcenter — cost centre identifier.")

(defconstant +role+
 (env-or "CISPEC_ROLE" "")
 "org.cispec.role — functional role slug.")

(defconstant +environment+
 (env-or "CISPEC_ENVIRONMENT" "")
 "org.cispec.environment — deployment environment slug.")

(defconstant +specversion+
 "1.0"
 "org.cispec spec version this module implements.")

;;; ----------------------------------------------------------------
;;; Label set — returns an alist of all non-empty key/value pairs
;;; ----------------------------------------------------------------

(defun label-set ()
 "Return an alist of (key . value) pairs for all non-empty org.cispec labels."
 (remove-if (lambda (pair) (string= "" (cdr pair)))
 (list (cons "org.cispec.organization" +organization+)
 (cons "org.cispec.orgunit" +orgunit+)
 (cons "org.cispec.application" +application+)
 (cons "org.cispec.version" +version+)
 (cons "org.cispec.owner" +owner+)
 (cons "org.cispec.oid" +oid+)
 (cons "org.cispec.duns" +duns+)
 (cons "org.cispec.customer" +customer+)
 (cons "org.cispec.costcenter" +costcenter+)
 (cons "org.cispec.role" +role+)
 (cons "org.cispec.environment" +environment+)
 (cons "org.cispec.specversion" +specversion+))))

;;; ----------------------------------------------------------------
;;; Verify required keys are populated
;;; ----------------------------------------------------------------

(defun verify-required ()
 "Signal an error if any required org.cispec key is empty.
 Call at load time to catch misconfigured builds early."
 (let ((required '((+organization+ . "org.cispec.organization")
 (+orgunit+ . "org.cispec.orgunit")
 (+application+ . "org.cispec.application")
 (+version+ . "org.cispec.version"))))
 (dolist (pair required)
 (when (string= "" (symbol-value (car pair)))
 (error "org.cispec: required label ~A is empty; ~
 set environment variable ~:*~A before loading."
 (cdr pair)))))
 t)

Usage in an ASDF system#

Add matrix-id as a dependency in your .asd file: