search

niemopen / niem-model

The NIEM reference data model
Other
14 stars 6 forks source link

Namespace ownership and package documentation #36

Open cdmgtri opened 1 year ago

cdmgtri commented 1 year ago

Transferred from a thread on the NBAC mailing list:

...I would like to ... discuss adding informational content somewhere that explains:

  1. The directory structure in https://github.com/niemopen/niem-model. If you look at the readme now, it explains the difference between 5.1 and 5.2. It doesn’t explain what is in the csv directory vs the json-ld directory vs the xlsx directory vs the xsd directory, or what any of them are, or what and of them are for.

  2. The directory structure in https://github.com/niemopen/niem-model/tree/main/xsd. This directory doesn’t even have a readme (albeit it would be ok if explained in it’s parent readme). Again, explain what’s where and what it is for.

  3. The mapping of which content is goes with which NBAC subcommittees (harmonization, domains) or stays at NBAC level. It’s reasonably straightforward (I assume) in the domain directory but who owns process for rest of them? I realize it’s complicated (ie by the file, and sometimes by the line in the file) but we should still understand and document the swimlanes.

  4. The mapping of ‘namespaces’ to NBAC/subcommittee. Some are straightforward (eg cyber owns cyber) but there are 56 namespaces (I presume since 56 lines in first tame of the xlsx version of neim 5.2) and most are not obvious to the uninformed. Eg I know (or at least I assume) STIX namespace is owned by cyber domain – but only because I am a SME in STIX (and maybe I’m wrong, maybe it’s in MilOps or in Core).

  5. What are ‘rules’/’process’ for making new namespace vs using existing.

cdmgtri commented 1 year ago

Initial response from thread:

We do have some documentation about the artifacts that are published as part of a NIEM version at https://niem.github.io/reference/release/artifacts/. It's based on the package structure of NIEM 4.0, so the folders are a little different than the 5.0-series, but all of the artifacts should be there. Including some of this information or linking to it from the readme could be helpful to others.

The different kinds of namespaces (again based on NIEM 4.0) are briefly described at https://niem.github.io/reference/concepts/namespace/#categories.

Documenting ownership of each namespace sounds like a good idea to me. This isn't exactly what you are looking for, but there are some instructions on the model repo wiki for sources to update some of the non-domain code set namespaces at https://github.com/niemopen/niem-model/wiki/Code-updates.

cdmgtri commented 1 year ago

Harmonization Subcommittee reviewed the namespace CSV files and thinks this address the requirements for items 3 and 4 in the original issue.

cdmgtri commented 1 year ago

Item 1 addressed in README at https://github.com/niemopen/niem-model/blob/dev/README.md#general-package-layout.

Item 2 addressed in README at https://github.com/niemopen/niem-model/blob/dev/README.md#xml-schema-folder-layout.

Items 3 and 4 addressed in new docs artifact at https://github.com/niemopen/niem-model/blob/dev/docs/namespaces-by-authority.csv.

Item 5 still outstanding. May already be addressed in NBAC governance documents.