Validation Pipeline

Validation Pipeline

Upon issuing a pull request, a user can expect that the following validations will be executed.

PR Validation checks

1. The @id property of the root element will be inspected.
   • If the value isn't a valid DTMI, the request will fail.
2. The @id property of the root element will be compared to the file path. The DTMI will be converted to lower-case; all : will be replaced with /; all ; will be replaced with -; .json will be appended.
   • This MUST match the file name or the request will fail.

   Example: a file defining dtmi:com:Example:Person;1 would be required to be in a file in ./dtmi/com/example/person-1.json. Similarly, a file defining dtmi:COM:ExAmPlE:PeRsOn;1 would be required to be in the file ./dtmi/com/example/person-1.json. This means that even though the DTMI are case-sensitive, the file structure holding the files is not. Additional information on the case sensitivity can be found in Resolution Convention

3. Any specified @id on sub elements will be checked to see if it resembles a DTMI. If not, it will be ignored.
   • If so, the DTMI MUST follow a namespace scoping.

   Example: a file specifying dtmi:com:example:person;1 can have a schema defined for dtmi:com:example:person:phoneNumber;1 but cannot have a schema defined for dtmi:com:telephone:number;1

4. The DTDL parser (likely existing C# implementation is expected to be used) will run against the submitted file(s) and ensure they will parse appropriately.
   • Failure to parse will fail the request.
5. Attempts will be made to scan for secrets and inappropriate content using existing tooling.
   • Any secrets of content items will be marked as warnings instead of errors.
6. The default branch will include branch security and ./CODEOWNERS file to alert any code owners that have been previously configured
7. No deletions or renames are allowed.
   • Will generate warnings as these could be major breaking changes to devices using them in production.

Expected validation failures

1. Invalid DTMI (see above)
2. Invalid path structure (see above)
3. Invalid sub DTMI (see above)
4. Invalid JSON. JSON document does not parse using standard language tools (likely C# due to DTDL parser requirements)
5. Invalid DTDL. Document does not parse using the DTDL parser utility.

Manual approvals

1. Ensure that a code owner (if any has been configured) has approved the request
2. Ensure that the validation has completed without errors.
3. Investigate any warnings (content/secrets)
4. If a separate workflow hasn't been established to apply new code owners, add entries for any newly created file that doesn't have an existing similar DTMI version

   Example: a user has created dtmi:com:Example:Person;1. There are no previously existing ./dtmi/com/example/person-*.json files. Add a new line to ./CODEOWNERS file dtmi/com/example/person-*.json. Include with the existing PR or create a followup PR.

   • Do not add codeowner entries if there are any existing versions of the DTMI.
5. Always SQUASH commits.
6. Ensure no deletions or renames exist without extenuating circumstances.
   • Changes to models that are in use are to be considered HUGE breaking changes.

Follow-ups

If your pull request has been open for (SLA to be determined), and has not been approved by a code owner. Raise an issue on the repository using the (template name to be determined) issue template.