About and owners

about says what an interface is for, who owns it, and the systems on each side. Nothing in it changes how messages flow: it's what people and tools read when something goes wrong.

# interfaces/adt-to-lab/interface.yaml, in part
about:
  description: ADT from Epic to the Sunquest lab
  owner: lab-it@hospital.org
  from:
    application: Epic
    vendor: Epic Systems
    hosts: [10.20.30.0/24, epic-bridge01.hospital.org]
  to:
    application: Sunquest Lab
    vendor: Sunquest

Why fill it in

• ductus impact answers "what does this touch?": ductus impact --vendor "Epic Systems" for a vendor's outage or breach, ductus impact --host 10.20.30.0/24 for a network change, with how each interface is affected (it sends to them, receives from them, queries their database) and who owns it. It knows only what's named (nuance): the application and vendor on each side, the hosts senders connect from, and the same on resources.yaml entries.
• On call, the web UI shows the description and owner on the interface's page, and alert rules can send to the owner: the person woken at 3 a.m. knows what broke and who to call.
• hosts is the one thing the engine can't learn from the configuration (who connects to it): with it, a firewall change can be traced to the interfaces it affects, and ductus validate warns when the source's allow: list would refuse a host named here.

ductus validate warns about an interface that doesn't name the application or vendor on each side; require_about: true in ductus.yaml makes it an error, once your existing interfaces are documented.

Owners

about.owner is who to ask about the interface: a person or a team. Write it as an email address (lab-it@hospital.org): an address matches the person's account (by its email) and survives a change of name, where a name might match two people or nobody.

• A person with an account shows as that person in the web UI, and their Interfaces page opens on what they own ("Mine"). With a directory, people who own something get their account before they first sign in, when they're in a Ductus group (nuance).

• A team without an account is reached through owners: in ductus.yaml, by the name the interfaces give:

  # ductus.yaml, in part
  owners:
    Lab Systems:
      email: lab-systems@hospital.org
  

• A destination with another owner (its code or its receiver is another team's) says so on the destination: owner: billing-it@hospital.org. Otherwise a destination's owner is its interface's (nuance).

• resources.yaml entries have an owner too: who renews a certificate, who looks after a database.

Alert rules with to: owner mail whoever owns the interface or destination (Alerts and owners). ductus owners lists who owns what; with the database it marks which owners are people with an account, and --check fails on an owner that reaches nobody (run it in CI). When someone leaves, ductus owners reassign --from old@hospital.org --to new@hospital.org moves everything they owned, in interface.yaml and resources.yaml alike: a change to commit, like any other (nuance).

• An owner is a person when the text names exactly one account (by username, email or display name); two accounts at one level name nobody, and the Owners page says so (nuance).
• Operators who own something start on their own interfaces in the console ("Mine") (nuance).
• Moving ownership in the console makes a preview of the change to commit to the project, not a change: the project in Git stays the truth (nuance).

Your own fields

custom, beside about, holds the documentation your company keeps that Ductus doesn't ask for (a BAA reference, the change ticket, the analyst, a runbook link): Documentation fields.