Property name namespaces

[coderpatros]

With v1.3 of the spec custom properties were introduced. But no real guidance on naming.

For example, CDX support is being added to Tern, a container SCA tool. One of the things Tern does is detect the OS, i.e. Debian. It refers to this information as os_guess. In that implementation this has been added as the property tern:os_guess.

This sort of namespacing can make it easier for folks trying to build tooling that processes CDX BOMs. They can now add support for tern:os_guess, if relevant to them, with less chance of a naming collision.

I also propose we have a standard way of namespacing CDX implementation specific properties. i.e. cdx:dotnet:whatever. Although that scheme should be defined at the CDX project level, the whatever can be delegated to each implementation.

Maybe there should be official package/build ecosystem namespaces too? i.e. cdx:nuget:whatever and cdx:msbuild:whatever? This could really help 3rd party tool implementers.

I think we should also specify a namespace for internal use only. We're probably all already throwing around CDX BOMs between our own internal tooling. But an internal namespace would mean that tooling, like the CLI, could support stripping properties that are only intended for internal usage before publishing the final "public" BOM.

So, I guess my proposal is:

• add documentation to the specification repo which details the high level recommended property namespacing scheme
• add references to that documentation in the description of properties in the spec itself
• create a new repo, cyclonedx-property-namespaces, with a file for each official CDX property namespace, i.e. cdx:nuget and a list of official NuGet specific property names (perhaps code owners can be used to delegate these to relevant implementation maintainers)

[nscuro]

I really like the idea, and I understand that there's immediate need for something like this. In fact, I have a pending issue that could make great use of it: CycloneDX/cyclonedx-gomod#29.

That being said, I think the namespace should be a (optional?) separate field (or attribute, for XML).

[stevespringett]

I like the idea of creating a taxonomy of pre-defined property namespaces for consistency reasons. I also like the fact that it will work with existing 1.3 spec without any changes - these are just recommendations.

Do you propose that we also include the property names themselves? For example:

cdx:nuget:package:metadata:releaseNotes

Or do you want to only define the namespacecdx:nuget?

[coderpatros]

At the top level we would define property namespaces like cdx, cdx:nuget, cdx:dotnet, etc.

Then there would be documented property names under each namespace.

I'm thinking a file structure something like this...

README.md <- describes general approach, some examples, maybe a local namespace
cdx.md <- taxonomy of all namespaces under cdx
cdx/nuget.md <- taxonomy of all namespaces/properties under cdx:nuget

Or, if a namespace gets large and the maintainer wants to break it up, the nuget one could be refactored to...

cdx/nuget/package.md
cdx/nuget/something-else.md

[nscuro]

I'd like to use this in the upcoming v1.0.0 release of cyclonedx-gomod. That would be the cdx:gomod namespace.

How can I assist in progressing this topic?

[coderpatros]

@nscuro I'll create a repo and get the basic content ready.

[coderpatros]

Repo is up here https://github.com/CycloneDX/cyclonedx-property-taxonomy

I've got it set to private. Be good to get some feedback from you both before I flip it to public.

[nscuro]

@coderpatros Thanks for setting up the repo. Looks good to me.

Maybe the syntax section could be extended so that namespaces SHOULD prefer to use lowercase letters. It would be nice to have some kind of uniformity in this regard.

[coderpatros]

Yeah, I was wondering about making it a requirement.

[stevespringett]

I think you're going to have to be very specific on namespaces. For example, you may consider requiring only ASCII characters.

[jkowalleck]

README states:

The process for registering a new top level namespace is to
create a new issue requesting it.

@coderpatros

an issue-template or -form for the purpose of "register new namespace" might come in handy for this.
in addition, having such a "register-namespace" template, the link in the README.md could be modified to select/apply this template automatically.

[coderpatros]

I haven't created the code owners file or an issue template or form yet.

But I have simplified the ABNF spec, specifically called out US ASCII requirements, added a link to the ABNF RFC for folks not familiar with it, and created a first cut of the gomod namespace taxonomy.

Unless I get any objections I'll flip this over to be public tomorrow night (UTC+10). We can always iterate on this further.

@nscuro pinging you to double check you are ok with the initial gomod taxonomy.