ucoProject / UCO

This repository is for development of the Unified Cyber Ontology.
Apache License 2.0
80 stars 34 forks source link

observable:firstName needs to contextualize as pertaining to contact, not identity:Person #350

Open ajnelson-nist opened 2 years ago

ajnelson-nist commented 2 years ago

Background

observable:firstName currently has the following definition, added in CP-5 (refactoring contacts):

The first name of a person.

It used to have the following definition:

The first name of the contact.

There was no specific rationale given for observable:firstName in the proposal. (This proposal has not been publicly exported, as became practice in a later UCO release.) This is the only focused remark on observable:firstName:

Modify definition comment of observable:firstName to abstract it from only Contacts

Someone reached out to me to ask when observable:firstName would be used instead of something from the identity namespace. I don't have a good answer for them, and I see no documentation to explain why this property moved towards potential confusion with properties in the identity namespace. Rationales for the changes in UCO CP-5 were not included in the proposal, beyond what seems to distill to something like "Reduce confusion between contacts in an address book and point-of-contacts for online services." Unfortunately, the implementation induces some confusion between the observable and identity namespaces now both trying to represent people, rather than observable objects.

Requirements

Requirement 1: The definition of observable:firstName should revert to The first name of the contact.

Requirement 2: observable:firstName should change to observable:contactFirstName, to separate scope of this property clearly away from identity:Person and more towards a contact record.

Requirement 3: Properties semantically close to observable:firstName should receive the same updates as in requirements 2 and 3. These include:

Non-requirements

The following other properties within observable:ContactFacet that do not match the observable:contact* pattern are not revised by this proposal. Note the namespace prefixes.

Potential Requirement 4: An example needs to be created (whether in UCO's unit tests, or among the CASE examples) that relates some observable:ObservableObject subclass, which uses observable:firstName, to an identity:Person.

Benefits

Risks

Competencies demonstrated

Competency 1

If a name "Bruce" is found in a knowledge base that records contacts and person details, they can be semantically distinguished as records of somehow-confirmed personal details, versus a record stored within a contact store somewhere. Take for instance these two objects, using UCO 0.8.0 terminology:

{
    "@context": {
        "kb": "http://example.org/kb/",
        "core": "https://ontology.unifiedcyberontology.org/uco/core/",
        "identity": "https://ontology.unifiedcyberontology.org/uco/identity/",
        "observable": "https://ontology.unifiedcyberontology.org/uco/observable/"
    },
    "@graph": [
        {
            "@id": "kb:contact-35eba411-d687-4a00-83d2-7fc30b771517",
            "@type": "observable:Contact",
            "core:hasFacet": {
                "@type": "observable:ContactFacet",
                "observable:firstName": "Bruce",
                "observable:lastName": "Wayne"
            }
        },
        {
            "@id": "kb:person-d2f7f2b0-c43c-40d7-9cfe-d38d0627e09a",
            "@type": "identity:Person"
            "core:hasFacet": {
                "@type": "identity:SimpleNameFacet",
                "identity:givenName": "Bruce",
                "identity:familyName": "Wayne"
            }
        }
    ]
}

This is compatible with observable:firstName retaining the definition "The first name of a person". However, a contact-record could describe this same person in a way that might render helpfully in the contacts or phone interface but otherwise be a semantic misuse of the fields.

{
    "@context": {
        "kb": "http://example.org/kb/",
        "core": "https://ontology.unifiedcyberontology.org/uco/core/",
        "observable": "https://ontology.unifiedcyberontology.org/uco/observable/"
    },
    "@graph": [
        {
            "@id": "kb:contact-c72b50a6-b255-4952-8db2-54f7ad396581",
            "@type": "observable:Contact",
            "core:hasFacet": {
                "@type": "observable:ContactFacet",
                "observable:firstName": "Gruff",
                "observable:lastName": "Voice"
            }
        }
    ]
}

Last, if the firstName field continues to call itself the first name of a person, it introduces a point of confusion of the source of that name. Is the name-association's source a person having the name, or somebody recording what they would want to remember as they were filling their address book in?

{
    "@context": {
        "kb": "http://example.org/kb/",
        "core": "https://ontology.unifiedcyberontology.org/uco/core/",
        "observable": "https://ontology.unifiedcyberontology.org/uco/observable/"
    },
    "@graph": [
        {
            "@id": "kb:contact-85009c9f-54fa-45b1-ae70-0c53c54fa79c",
            "@type": "observable:Contact",
            "core:hasFacet": {
                "@type": "observable:ContactFacet",
                "observable:firstName": "Bat",
                "observable:lastName": "Man"
            }
        }
    ]
}

There should be no reason UCO assists with confusing those fields with a person's name.

Solution summary

Doing so addresses requirements 1, 2, and 3.

Coordination