{
  "resourceType": "StructureDefinition",
  "id": "nexus-emr-task-note",
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
      "valueCode": "trial-use"
    }
  ],
  "url": "https://fhir.apps.health/StructureDefinition/nexus-emr-task-note",
  "name": "NexusEmrTaskNote",
  "title": "Task Note (one conversation turn)",
  "status": "draft",
  "date": "2026-08-19",
  "publisher": "WELLSTAR Technologies Corp.",
  "description": "One turn in a task's conversation: who said it, when, and what they said. Both people and machine actors (harness graphs, decision-support rules) author turns. Because R4 does not permit `Device` as an `Annotation.author` target and a profile cannot widen it, a machine-authored turn is an identifier-only logical reference under the nexus-harness-graph or nexus-cds-rule NamingSystem, carrying a display and no literal reference; the identifier's system is what says the author is a graph. Human authors use the element normally.",
  "purpose": "Give the conversation turn on a Task a named, checkable shape -- including machine authorship, which base R4 cannot express directly.",
  "fhirVersion": "4.0.1",
  "mapping": [
    {
      "identity": "v2",
      "uri": "http://hl7.org/v2",
      "name": "HL7 v2 Mapping"
    },
    {
      "identity": "rim",
      "uri": "http://hl7.org/v3",
      "name": "RIM Mapping"
    }
  ],
  "kind": "complex-type",
  "abstract": false,
  "type": "Annotation",
  "baseDefinition": "http://hl7.org/fhir/StructureDefinition/Annotation",
  "derivation": "constraint",
  "snapshot": {
    "element": [
      {
        "id": "Annotation",
        "path": "Annotation",
        "short": "Text node with attribution",
        "definition": "A  text note which also  contains information about who made the statement and when.",
        "comment": "For systems that do not have structured annotations, they can simply communicate a single annotation with no author or time.  This element may need to be included in narrative because of the potential for modifying information.  *Annotations SHOULD NOT* be used to communicate \"modifying\" information that could be computable. (This is a SHOULD because enforcing user behavior is nearly impossible).",
        "min": 0,
        "max": "*",
        "base": {
          "path": "Annotation",
          "min": 0,
          "max": "*"
        },
        "condition": [
          "ele-1"
        ],
        "constraint": [
          {
            "key": "ele-1",
            "severity": "error",
            "human": "All FHIR elements must have a @value or children",
            "expression": "hasValue() or (children().count() > id.count())",
            "xpath": "@value|f:*|h:div",
            "source": "http://hl7.org/fhir/StructureDefinition/Element"
          },
          {
            "key": "nexus-note-agent-author",
            "severity": "error",
            "human": "A turn authored by a machine actor SHALL be an identifier-only logical reference: `author.identifier` under the nexus-harness-graph or nexus-cds-rule NamingSystem, carrying a display and NO literal `reference`. Device is not an allowed target of Annotation.author in R4, so the identifier system carries the identity; `Reference.type` is omitted deliberately rather than asserting a target the element does not permit.",
            "expression": "author.ofType(Reference).identifier.where(system = 'https://fhir.apps.health/NamingSystem/nexus-harness-graph' or system = 'https://fhir.apps.health/NamingSystem/nexus-cds-rule').exists() implies (author.ofType(Reference).reference.empty() and author.ofType(Reference).type.empty() and author.ofType(Reference).display.exists() and author.ofType(Reference).identifier.value.exists())",
            "source": "https://fhir.apps.health/StructureDefinition/nexus-emr-task-note"
          }
        ],
        "isModifier": false,
        "mapping": [
          {
            "identity": "rim",
            "map": "n/a"
          },
          {
            "identity": "v2",
            "map": "N/A"
          },
          {
            "identity": "rim",
            "map": "Act"
          }
        ]
      },
      {
        "id": "Annotation.id",
        "path": "Annotation.id",
        "representation": [
          "xmlAttr"
        ],
        "short": "Unique id for inter-element referencing",
        "definition": "Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.",
        "min": 0,
        "max": "1",
        "base": {
          "path": "Element.id",
          "min": 0,
          "max": "1"
        },
        "type": [
          {
            "code": "http://hl7.org/fhirpath/System.String",
            "extension": [
              {
                "url": "http://hl7.org/fhir/StructureDefinition/structuredefinition-fhir-type",
                "valueUrl": "string"
              }
            ]
          }
        ],
        "isModifier": false,
        "isSummary": false,
        "mapping": [
          {
            "identity": "rim",
            "map": "n/a"
          }
        ]
      },
      {
        "id": "Annotation.extension",
        "path": "Annotation.extension",
        "slicing": {
          "discriminator": [
            {
              "type": "value",
              "path": "url"
            }
          ],
          "description": "Extensions are always sliced by (at least) url",
          "rules": "open"
        },
        "short": "Additional content defined by implementations",
        "definition": "May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance  applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.",
        "comment": "There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions.  The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.",
        "alias": [
          "extensions",
          "user content"
        ],
        "min": 0,
        "max": "*",
        "base": {
          "path": "Element.extension",
          "min": 0,
          "max": "*"
        },
        "type": [
          {
            "code": "Extension"
          }
        ],
        "constraint": [
          {
            "key": "ele-1",
            "severity": "error",
            "human": "All FHIR elements must have a @value or children",
            "expression": "hasValue() or (children().count() > id.count())",
            "xpath": "@value|f:*|h:div",
            "source": "http://hl7.org/fhir/StructureDefinition/Element"
          },
          {
            "key": "ext-1",
            "severity": "error",
            "human": "Must have either extensions or value[x], not both",
            "expression": "extension.exists() != value.exists()",
            "xpath": "exists(f:extension)!=exists(f:*[starts-with(local-name(.), \"value\")])",
            "source": "http://hl7.org/fhir/StructureDefinition/Extension"
          }
        ],
        "isModifier": false,
        "isSummary": false,
        "mapping": [
          {
            "identity": "rim",
            "map": "n/a"
          }
        ]
      },
      {
        "id": "Annotation.author[x]",
        "path": "Annotation.author[x]",
        "short": "Who said it: a person, or a machine actor (identifier-only reference)",
        "definition": "The author of this turn.\n\nA **person** is referenced normally (`authorReference` to a Practitioner, Patient, RelatedPerson or\nOrganization), or named as free text with `authorString` where no structured reference exists.\n\nA **machine actor** is an identifier-only logical reference: `authorReference.identifier` under its\nproducing registry's namespace -- `https://fhir.apps.health/NamingSystem/nexus-harness-graph` naming\na harness graph, or `https://fhir.apps.health/NamingSystem/nexus-cds-rule` naming a decision-support\nrule -- with\n`authorReference.display` carrying a readable name and NO `authorReference.reference`. `Device` is\nnot an allowed target of this element in R4 and a profile cannot add one, so the identifier system\ncarries the identity. `Reference.type` is omitted deliberately: setting it to `Device` would assert\na target the element does not permit.",
        "comment": "Required here though optional in base R4: an unattributed turn is a statement in the record with nobody behind it. **PractitionerRole is NOT a permitted target in R4 even though `Task.owner` permits it** -- a task can be owned by a role and still have every turn authored by a person, and a writer that reaches for the same reference in both places will produce an invalid note. (R5 adds PractitionerRole; R4 does not, and a profile cannot widen the list.) For agent authors see `nexus-note-agent-author`, which enforces the identifier-only shape. Granularity for a machine author is the GRAPH or the RULE -- the unit a clinician or auditor recognises -- never the model or the prompt; per-model trace stays with the producer.",
        "min": 1,
        "max": "1",
        "base": {
          "path": "Annotation.author[x]",
          "min": 0,
          "max": "1"
        },
        "type": [
          {
            "code": "Reference",
            "targetProfile": [
              "http://hl7.org/fhir/StructureDefinition/Practitioner",
              "http://hl7.org/fhir/StructureDefinition/Patient",
              "http://hl7.org/fhir/StructureDefinition/RelatedPerson",
              "http://hl7.org/fhir/StructureDefinition/Organization"
            ]
          },
          {
            "code": "string"
          }
        ],
        "constraint": [
          {
            "key": "ele-1",
            "severity": "error",
            "human": "All FHIR elements must have a @value or children",
            "expression": "hasValue() or (children().count() > id.count())",
            "xpath": "@value|f:*|h:div",
            "source": "http://hl7.org/fhir/StructureDefinition/Element"
          }
        ],
        "mustSupport": true,
        "isModifier": false,
        "isSummary": true,
        "mapping": [
          {
            "identity": "v2",
            "map": "N/A"
          },
          {
            "identity": "rim",
            "map": "Act.participant[typeCode=AUT].role"
          }
        ]
      },
      {
        "id": "Annotation.time",
        "path": "Annotation.time",
        "short": "When the turn was made -- the thread's ordering key",
        "definition": "When this turn was made. Required here though optional in base R4, because the turns are read as an ordered thread and a turn with no time cannot be placed in it.",
        "comment": "Turns are read oldest-first by `time`. This element is the ordering key, which is why it is required: one undated turn makes the whole conversation's order a guess.",
        "min": 1,
        "max": "1",
        "base": {
          "path": "Annotation.time",
          "min": 0,
          "max": "1"
        },
        "type": [
          {
            "code": "dateTime"
          }
        ],
        "constraint": [
          {
            "key": "ele-1",
            "severity": "error",
            "human": "All FHIR elements must have a @value or children",
            "expression": "hasValue() or (children().count() > id.count())",
            "xpath": "@value|f:*|h:div",
            "source": "http://hl7.org/fhir/StructureDefinition/Element"
          }
        ],
        "mustSupport": true,
        "isModifier": false,
        "isSummary": true,
        "mapping": [
          {
            "identity": "v2",
            "map": "N/A"
          },
          {
            "identity": "rim",
            "map": "Act.effectiveTime"
          }
        ]
      },
      {
        "id": "Annotation.text",
        "path": "Annotation.text",
        "short": "What was said (markdown)",
        "definition": "The text of the annotation in markdown format.",
        "comment": "Markdown, per base R4. A turn carries prose, not structured payload: a turn that needs to cite chart resources cites them from the Task (`focus`, `input`, `supportingInformation`), not from inside the annotation. See the Task profile's note element for the graduation valve if that ever becomes insufficient.",
        "min": 1,
        "max": "1",
        "base": {
          "path": "Annotation.text",
          "min": 1,
          "max": "1"
        },
        "type": [
          {
            "code": "markdown"
          }
        ],
        "constraint": [
          {
            "key": "ele-1",
            "severity": "error",
            "human": "All FHIR elements must have a @value or children",
            "expression": "hasValue() or (children().count() > id.count())",
            "xpath": "@value|f:*|h:div",
            "source": "http://hl7.org/fhir/StructureDefinition/Element"
          }
        ],
        "mustSupport": true,
        "isModifier": false,
        "isSummary": true,
        "mapping": [
          {
            "identity": "v2",
            "map": "N/A"
          },
          {
            "identity": "rim",
            "map": "Act.text"
          }
        ]
      }
    ]
  },
  "differential": {
    "element": [
      {
        "id": "Annotation",
        "path": "Annotation",
        "constraint": [
          {
            "key": "nexus-note-agent-author",
            "severity": "error",
            "human": "A turn authored by a machine actor SHALL be an identifier-only logical reference: `author.identifier` under the nexus-harness-graph or nexus-cds-rule NamingSystem, carrying a display and NO literal `reference`. Device is not an allowed target of Annotation.author in R4, so the identifier system carries the identity; `Reference.type` is omitted deliberately rather than asserting a target the element does not permit.",
            "expression": "author.ofType(Reference).identifier.where(system = 'https://fhir.apps.health/NamingSystem/nexus-harness-graph' or system = 'https://fhir.apps.health/NamingSystem/nexus-cds-rule').exists() implies (author.ofType(Reference).reference.empty() and author.ofType(Reference).type.empty() and author.ofType(Reference).display.exists() and author.ofType(Reference).identifier.value.exists())",
            "source": "https://fhir.apps.health/StructureDefinition/nexus-emr-task-note"
          }
        ]
      },
      {
        "id": "Annotation.author[x]",
        "path": "Annotation.author[x]",
        "short": "Who said it: a person, or a machine actor (identifier-only reference)",
        "definition": "The author of this turn.\n\nA **person** is referenced normally (`authorReference` to a Practitioner, Patient, RelatedPerson or\nOrganization), or named as free text with `authorString` where no structured reference exists.\n\nA **machine actor** is an identifier-only logical reference: `authorReference.identifier` under its\nproducing registry's namespace -- `https://fhir.apps.health/NamingSystem/nexus-harness-graph` naming\na harness graph, or `https://fhir.apps.health/NamingSystem/nexus-cds-rule` naming a decision-support\nrule -- with\n`authorReference.display` carrying a readable name and NO `authorReference.reference`. `Device` is\nnot an allowed target of this element in R4 and a profile cannot add one, so the identifier system\ncarries the identity. `Reference.type` is omitted deliberately: setting it to `Device` would assert\na target the element does not permit.",
        "comment": "Required here though optional in base R4: an unattributed turn is a statement in the record with nobody behind it. **PractitionerRole is NOT a permitted target in R4 even though `Task.owner` permits it** -- a task can be owned by a role and still have every turn authored by a person, and a writer that reaches for the same reference in both places will produce an invalid note. (R5 adds PractitionerRole; R4 does not, and a profile cannot widen the list.) For agent authors see `nexus-note-agent-author`, which enforces the identifier-only shape. Granularity for a machine author is the GRAPH or the RULE -- the unit a clinician or auditor recognises -- never the model or the prompt; per-model trace stays with the producer.",
        "min": 1,
        "mustSupport": true
      },
      {
        "id": "Annotation.time",
        "path": "Annotation.time",
        "short": "When the turn was made -- the thread's ordering key",
        "definition": "When this turn was made. Required here though optional in base R4, because the turns are read as an ordered thread and a turn with no time cannot be placed in it.",
        "comment": "Turns are read oldest-first by `time`. This element is the ordering key, which is why it is required: one undated turn makes the whole conversation's order a guess.",
        "min": 1,
        "mustSupport": true
      },
      {
        "id": "Annotation.text",
        "path": "Annotation.text",
        "short": "What was said (markdown)",
        "comment": "Markdown, per base R4. A turn carries prose, not structured payload: a turn that needs to cite chart resources cites them from the Task (`focus`, `input`, `supportingInformation`), not from inside the annotation. See the Task profile's note element for the graduation valve if that ever becomes insufficient.",
        "mustSupport": true
      }
    ]
  }
}