IF Commons GitHub

governance/exchange

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-integrations-governance FR-010, 0002-integrations-governance FR-011, 0002-integrations-governance FR-012, 0002-integrations-governance FR-013, 0002-integrations-governance FR-014, 0002-integrations-governance FR-015

The governance of exchange (commons integrations 0002-integrations-governance): standards as registry entries with identity, version and licence, the four levels a standard is at (syntax, schema, profile, terminology), the agreement with a trading partner, the protection of what is exchanged and the obligations that follow. It names no syntax and no transport: X12, HL7 v2 and FHIR are entries of the registry, not words of this module.

A standard's licence is data with the rule that follows from it (Embedding): what may be committed to this public repository and what must be read from a copy the user supplies. Payloads are classified (Classification) and a classification says whether the payload may appear in a log, a hint or a trace; for every classification above public it may not.

Source: commons/integrations/src/governance/exchange.ts

10 of 34 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Leveltypeno test imports it
type Level = "syntax" | "schema" | "profile" | "terminology";

The four levels a standard is at.

LEVELSconstno test imports it
const LEVELS: readonly Level[]

The levels of validation a message passes, in order: syntax, schema, profile and terminology.

Reftypeno test imports it
type Ref<L extends Level> = { readonly level: L; readonly urn: StandardUrn };

A reference to a standard at one level; the level is in the type so that a schema cannot stand where a terminology is wanted.

refconst
const ref: <L extends Level>(level: L, urn: StandardUrn) => Ref<L>

A reference at a level.

Imported by 32 tests of the run (32 passed, 0 failed): the library's results

Familytypeno test imports it
type Family = "message" | "document" | "resource-api" | "vocabulary" | "file-format";

What kind of thing a standard defines.

Basistypeno test imports it
type Basis =
  | { readonly kind: "adopts"; readonly of: StandardUrn }
  | { readonly kind: "specializes"; readonly of: StandardUrn }
  | { readonly kind: "maps"; readonly to: StandardUrn }
  | { readonly kind: "unaligned"; readonly reason: string };

How a standard relates to the standard it comes from (commons 0018-standards-first).

Embeddingtypeno test imports it
type Embedding =
  | "allowed" // the text and its machine-readable definitions may be committed, with the licence cited
  | "user-supplied" // only a copy the user holds under a licence is read; nothing of it is committed
  | "refused";

What the licence of a standard allows this repository to hold.

Licensetype
type License = { readonly spdx: string; readonly embedding: Embedding; readonly terms: string };

A licence as data: its SPDX identifier (or a LicenseRef- of the holder's terms), what it allows, and the text that cites the terms.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Standardtypeno test imports it
type Standard = { readonly urn: StandardUrn; readonly level: Level; readonly family: Family; readonly title: str… (419 characters)
type Standard = {
  readonly urn: StandardUrn;
  readonly level: Level;
  readonly family: Family;
  readonly title: string;
  readonly issuer: string;
  readonly version: string;
  readonly basis: Basis;
  readonly location: string;
  readonly license: License;
  /** The digest of what was imported; absent where nothing was (a standard that is read from the user's copy). */
  readonly sha256: Sha256 | undefined;
};

A standard: a registry entry with a stable identity (commons 0018-standards-first FR-006).

BindingStrengthtypeno test imports it
type BindingStrength = "required" | "extensible" | "preferred" | "example";

What a binding of a terminology demands of a code.

TerminologyBindingtypeno test imports it
type TerminologyBinding = { readonly path: string; readonly terminology: Ref<"terminology">; readonly strength: BindingStrength };

A binding of an element to a terminology.

ProfileBindingtypeno test imports it
type ProfileBinding = { readonly profile: Ref<"profile">; readonly schema: Ref<"schema"> };

A profile bound to the schema it constrains.

Sourcetypeno test imports it
type Source = "embedded-in-package" | "user-supplied" | "published-by-issuer";

Whether a standard may be loaded from a source of the given kind.

sourceAllowedfunction
function sourceAllowed(license: License, source: Source): boolean

Whether the licence of a standard lets this source be used: a pure decision.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Classificationtypeno test imports it
type Classification = "public" | "internal" | "confidential" | "protected-health-information";

How sensitive what is exchanged is.

CLASSIFICATIONSconst
const CLASSIFICATIONS: readonly Classification[]

The classifications of data an agreement may name, from public to protected health information.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

mayAppearInLogsfunction
function mayAppearInLogs(c: Classification): boolean

Where a payload of a classification may appear: only a public one in a log, a hint or a trace; no other, ever.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

MinimumNecessarytypeno test imports it
type MinimumNecessary =
  | { readonly kind: "whole-record" }
  | { readonly kind: "listed-elements"; readonly paths: readonly string[] }
  | { readonly kind: "treatment-exempt" };

How much of a record a recipient may be given.

Handlingtypeno test imports it
type Handling = { readonly encryptedInTransit: true; readonly encryptedAtRest: boolean; readonly retention: Duration };

What is done with a payload at rest and in flight.

DataProtectiontypeno test imports it
type DataProtection = { readonly classification: Classification; readonly handling: Handling; readonly minimumNecessary: MinimumNecessary };

The data protection of an exchange.

AckRequirementtypeno test imports it
type AckRequirement =
  | { readonly kind: "x12-ta1"; readonly within: Duration }
  | { readonly kind: "x12-999"; readonly within: Duration }
  | { readonly kind: "hl7-ack"; readonly mode: "original" | "enhanced"; readonly within: Duration }
  | { readonly kind: "fhir-operation-outcome"; readonly within: Duration };

The acknowledgement a partner requires, by standard.

Directiontypeno test imports it
type Direction = "inbound" | "outbound" | "both";

Which direction messages flow with a partner.

Obligationtypeno test imports it
type Obligation =
  | { readonly kind: "validate"; readonly levels: readonly Level[] }
  | { readonly kind: "acknowledge" }
  | { readonly kind: "log"; readonly what: "metadata-only" }
  | { readonly kind: "keep"; readonly for: Duration };

What an exchange must do.

ServiceLevelstypeno test imports it
type ServiceLevels = { readonly ackWithin: Duration; readonly maxAttempts: number };

The service levels agreed: how long until an acknowledgement is overdue and how many times a send is tried.

ExchangeTransportPolicytypeno test imports it
type ExchangeTransportPolicy =
  | { readonly kind: "https"; readonly endpoint: string; readonly auth: "oauth2-backend-services" | "mutual-tls" | "api-key" }
  | { readonly kind: "sftp"; readonly host: string }
  | { readonly kind: "as2"; readonly endpoint: string }
  | { readonly kind: "mllp"; readonly host: string; readonly port: number };

How a partner is reached; the credential is a reference.

ExchangeAgreementtype
type ExchangeAgreement = { readonly id: AgreementId; readonly partner: PartnerId; readonly direction: Direction; … (569 characters)
type ExchangeAgreement = {
  readonly id: AgreementId;
  readonly partner: PartnerId;
  readonly direction: Direction;
  readonly syntax: Ref<"syntax">;
  readonly schemas: readonly Ref<"schema">[];
  readonly profiles: readonly ProfileBinding[];
  readonly bindings: readonly TerminologyBinding[];
  readonly acknowledgements: readonly AckRequirement[];
  readonly serviceLevels: ServiceLevels;
  readonly protection: DataProtection;
  readonly obligations: readonly Obligation[];
  readonly transport: ExchangeTransportPolicy;
  readonly credential: CredentialRef;
};

An exchange agreement with a trading partner.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

AgreementProblemtypeno test imports it
type AgreementProblem =
  | { readonly kind: "no-schema" }
  | { readonly kind: "unacknowledged"; readonly needs: "acknowledgement-requirement" }
  | { readonly kind: "validates-no-level" }
  | { readonly kind: "log-would-carry-payload"; readonly classification: Classification }
  | { readonly kind: "attempts-not-positive" }
  | { readonly kind: "retention-shorter-than-keep" };

What is wrong with an agreement.

agreementProblemsfunction
function agreementProblems(a: ExchangeAgreement): readonly AgreementProblem[]

Every problem of an agreement against the standards registry; none where it may be used.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

StandardsRegistrytype
type StandardsRegistry = ReadonlyMap<StandardUrn, Standard>;

A standard registry: typed entries by urn.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

RegistryErrortypeno test imports it
type RegistryError =
  | { readonly kind: "duplicate"; readonly urn: StandardUrn }
  | { readonly kind: "urn-mismatch"; readonly urn: StandardUrn; readonly want: string }
  | { readonly kind: "no-terms"; readonly urn: StandardUrn };

Why an entry is refused by a registry.

registerfunction
function register(reg: StandardsRegistry, s: Standard): Result<StandardsRegistry, RegistryError>

The registry with one more entry, or why not.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

EmbeddedContenttypeno test imports it
type EmbeddedContent = { readonly path: string; readonly standard: StandardUrn };

A file a package holds, with the standard whose content it embeds.

EmbeddingFindingtypeno test imports it
type EmbeddingFinding =
  | { readonly kind: "embedded-not-allowed"; readonly path: string; readonly standard: StandardUrn; readonly embedding: Embedding }
  | { readonly kind: "embedded-unknown-standard"; readonly path: string; readonly standard: StandardUrn };

A finding of the publication gate.

embeddingFindingsfunction
function embeddingFindings(reg: StandardsRegistry, embedded: readonly EmbeddedContent[]): readonly EmbeddingFinding[]

The refusal to publish embedded content a licence does not allow: a finding for each embedded file whose standard's licence is not allowed or is not in the registry.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.