Modify validation for Phone Numbers

[Telos-sa]

User Story

Currently the listed type for metadata>parties>telephone-numbers>number is a string, which has the regular expression pattern "\S(.*\S)?":

When validating using the oscal-cli, this field instead uses the regex pattern "^[0-9]{3}[0-9]{1,12}$" for validation, and throws warnings for varying (fake) phone numbers:

Goals

Validate using the string regex pattern which is outlined in the schema
Or
Create a new datatype for telephone-numbers>number that lists the regex pattern that is actually being used for validation

Dependencies

No response

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

(For reviewers: The wiki has guidance on code review and overall issue review for completeness.)

Revisions

No response

[iMichaela]

@Telos-sa - can you please provide the version of the oscal-cli you are using. I am assuming it is a FedRAMP constraint. While a better implementation is desired, we would need to see if other international numbers are supported.

[iMichaela]

How will extensions be noted when the regex pattern "^[0-9]{3}[0-9]{1,12}$" is used? Also numbers with prefixes marked with () ?

[Telos-sa]

@iMichaela This is version 2.0.2 of the base OSCAL validator (no FedRAMP constraints were used). I downloaded the pre-built version from https://repo1.maven.org/maven2/dev/metaschema/oscal/oscal-cli-enhanced/2.0.2/ as outlined on https://github.com/metaschema-framework/oscal-cli. If this is an incorrect oscal-cli please let us know where we can go to install the correct.

[iMichaela]

NIST oscal-cli latest release is v1.0.3. The version you point out to was generated not by NIST so we have no control over the OSCAL metaschema definitions (models) used to generate that version. If this is the one provided by FedRAMP and generated under metaschema-framework repo, please raise those concerns with the developers. There is no NIST oscal-cli v2.0.2. This is the version FedRAMP demo-ed last week. Please raise those issues with FedRAMP because the OSCAL version (when constraints are not applied) should be the official OSCAL release v1.1.2 or earlier.
Can you please provide the version of OSCAL displayed by the tool?

https://github.com/metaschema-framework/oscal-cli is not a NIST repo. Here is NIST repo: https://github.com/usnistgov/oscal-cli

Thank you.

[Telos-sa]

Apologies for the version confusion, I have installed v1.0.3 from https://github.com/usnistgov/oscal-cli:

The same warnings are still present in v1.0.3

It makes sense that telephone-numbers>number would have a different validation regex pattern than strings, but that is not outlined in the v1.1.2 OSCAL metaschema.

telephone-numbers section under parties:

"telephone-numbers":{
    "type":"array",
    "minItems":1,
    "items":{
        "$ref":"#field_oscal-metadata_telephone-number"
    }
}

Assembly for field_oscal-metadata_telephone-number:

"oscal-ssp-oscal-metadata:telephone-number":{
    "title":"Telephone Number",
    "description":"A telephone service number as defined by ITU-T E.164.",
    "$id":"#field_oscal-metadata_telephone-number",
    "type":"object",
    "properties":{
        "type":{
            "title":"type flag",
            "description":"Indicates the type of phone number.",
            "anyOf":[
                {
                    "$ref":"#/definitions/StringDatatype"
                },
                {
                    "enum":[
                        "home",
                        "office",
                        "mobile"
                    ]
                }
            ]
        },
        "number":{
            "$ref":"#/definitions/StringDatatype"
        }
    },
    "required":[
        "number"
    ],
    "additionalProperties":false
}

StringDataType definition:

"StringDatatype":{
    "description":"A non-empty string with leading and trailing whitespace disallowed. Whitespace is: U+9, U+10, U+32 or [ \n\t]+",
    "type":"string",
    "pattern":"^\\S(.*\\S)?$"
}

The regex pattern "^[0-9]{3}[0-9]{1,12}$" is used by the oscal-cli for validation, but is not outlined anywhere in the metaschema.

[wendellpiez]

Hi, - note, this is corrected from earlier. (I checked again!)

The constraint being discussed is presumably this "WARNING"-level constraint at

OSCAL/src/metaschema/oscal_metadata_metaschema.xml

Line 1052 in 4f02dac

<matches level="WARNING" target="." regex="^[0-9]{3}[0-9]{1,12}$">

This is non-operative in the JSON schema (or XSD) but will throw an error in a processor implementing the constraint as expressed. Presumably it's a WARNING because it was understood to be too broad.

We could make the warning go away by removing or relaxing the constraint.

[iMichaela]

Since many numbers can be noted with extensions that need to be documented with the phone number, or other, a with a + sign in front for international numbers , or have area code in parentheses, the warning (to me) is meant to raise human's attention to ensure the inserted number is correct, when non-numeric values are used. Tere is also the SIP protocol (https://en.wikipedia.org/wiki/SIP_URI_scheme) with valid format like sip:1-999-123-4567@voip-provider.example.net
Is the suggestion here to remove the regex="^[0-9]{3}[0-9]{1,12}$" constraint all together and not use it as a semi-validation mechanism for numeric-only phone numbers?

[GaryGapinski]

Ah, "telephone numbers". They can be and are anything you want them to be. The word numbers is inadequate. Perhaps even telephone.

TL;DR: The constraint mentioned — \S(.*\S)? — is sufficient to encompass almost all telephone numbers of a length greater than 0 and is admirably catholic. It cannot express an absent value (the initial \S demands an initial non-space character). However, this constraint does not appear in the most recent (v1.1.1) XML and JSON Schemas. The schema documentation mentions that telephone-number is "A telephone service number as defined by ITU-T E.164.".

Without locale-specific presentation/formatting, even numeric telephone "numbers" look bad if subjected to artifical and unwarranted constraints.

Some references:

• Normative: ITU-T E.164. Some folks do not conform but happily make and receive calls anyway.
• Informative: https://en.wikipedia.org/wiki/E.164.
• Normative: ITU-T E.123. To borrow a phrase from Mark Twain, E.123 is commonly flung down and danced upon. ¹
• Informative: https://en.wikipedia.org/wiki/E.123.
• Normative: RFC2806.
• Normative: RFC3261. No such thing as all-numeric.
• Informative: https://en.wikipedia.org/wiki/SIP_URI_scheme.
• The above are, btw, over 20 years old. They lack currency and exhibit flaws and inconsistencies.
• Informative: https://en.wikipedia.org/wiki/National_conventions_for_writing_telephone_numbers.
• Normative: RFC5724.

Examples (mostly not E.123) (I frequently find demarcation of treasured "number" syllables via periods, hyphens, spaces, parentheses):

• Deutsche Bundesnachrichtendienst contact page.
• UK SIS (MI6) contact page.
• CISA contact page.
• GSA contact page.
• Telos contact page.

¹ Fenimore Cooper's Literary Offences #7