app.domain.fields

Validators for individual ADR frontmatter field values.

Each validator takes the raw value loaded from YAML plus the field name and returns the normalised value together with any issues. Validators never raise for bad content. They are used by app.domain.records.parse_record().

Public API: ISO_DATE_RE, UUID_RE, parse_uuid(), parse_uuid_list(), parse_iso_date(), parse_date(), parse_text(), parse_erratum_type(), parse_text_list().

app.domain.fields.ISO_DATE_RE = re.compile('^\\d{4}-\\d{2}-\\d{2}$')

Accepted spelling of dates: YYYY-MM-DD.

app.domain.fields.UUID_RE = re.compile('^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.IGNORECASE)

Accepted spelling of UUIDs: canonical hyphenated form, any case.

app.domain.fields.shown(value)

Render a value for an issue message, truncated to a sane length.

Parameters:

value (object) – Any loaded YAML value.

Return type:

str

Returns:

A short quoted representation.

app.domain.fields.parse_uuid(value, field)

Validate a single UUID value.

Parameters:

  • value (object) – The loaded value.

  • field (str) – Field name used in the message.

Return type:

tuple[UUID | None, Issue | None]

Returns:

The UUID and None, or None and a bad_uuid issue.

app.domain.fields.parse_uuid_list(value, field)

Validate a list of UUIDs (a single UUID string is also accepted).

Invalid entries are dropped and reported; duplicates are removed while keeping the first occurrence.

Parameters:

  • value (object) – The loaded value.

  • field (str) – Field name used in messages.

Return type:

tuple[tuple[UUID, ...], list[Issue]]

Returns:

The valid UUIDs in order, and the issues found.

app.domain.fields.parse_iso_date(text)

Parse a strict YYYY-MM-DD string.

Parameters:

text (str) – Candidate date text.

Return type:

date | None

Returns:

The date, or None if the text is not a valid date.

app.domain.fields.parse_date(value, field)

Validate a date value written as YYYY-MM-DD.

Parameters:

  • value (object) – The loaded value (a string; explicit YAML dates are accepted too).

  • field (str) – Field name used in the message.

Return type:

tuple[date | None, Issue | None]

Returns:

The date and None, or None and a bad_date issue.

app.domain.fields.parse_text(value, field)

Validate a non-empty single-line text value.

Parameters:

  • value (object) – The loaded value.

  • field (str) – Field name used in the message.

Return type:

tuple[str | None, Issue | None]

Returns:

The stripped text and None, or None and a bad_field_type issue.

app.domain.fields.parse_erratum_type(value, field)

Validate an erratum type value (case-insensitive).

Parameters:

  • value (object) – The loaded value.

  • field (str) – Field name used in the message.

Return type:

tuple[ErratumType | None, Issue | None]

Returns:

The type and None, or None and a bad_erratum_type issue.

app.domain.fields.parse_text_list(value, field)

Validate a list of text entries (a single text is also accepted).

Scalar entries such as numbers are converted to text; empty and nested entries are dropped and reported.

Parameters:

  • value (object) – The loaded value.

  • field (str) – Field name used in messages.

Return type:

tuple[tuple[str, ...], list[Issue]]

Returns:

The entries in order, and the issues found.