Some discrepancies and suggestions on the different JSON schemas specified in this repo

[yohhaan]

Hello,

I have noticed a few discrepancies in the JSON schemas that are specified in this repository, you will find next a list of comments with some suggestions. I am submitting this as an issue rather than a pull request as per the FAQs. Also, a note: I have not checked if the automated tests need to be updated in some way accordingly to these suggested changes.

In SCHEMA.json:

• "contact" : {"type": "string"}, should be listed under the properties for the nested list of objects under "sets" and not for the global object as it currently is.
• additionally, the "oneOf" keyword could also be used the following way to make sure that at least one of these 3 entries is present:

  "oneOf": [
          {
              "required": [
                  "associatedSites"
              ]
          },
          {
              "required": [
                  "serviceSites"
              ]
          },
          {
              "required": [
                  "ccTLDs"
              ]
          }
      ],

• This would give the following updated schema:

{
    "type": "object",
    "properties": {
        "sets": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "contact": {
                        "type": "string"
                    },
                    "ccTLDs": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "primary": {
                        "type": "string"
                    },
                    "associatedSites": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "serviceSites": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "rationaleBySite": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "primary",
                    "contact"
                ],
                "oneOf": [
                    {
                        "required": [
                            "associatedSites"
                        ]
                    },
                    {
                        "required": [
                            "serviceSites"
                        ]
                    },
                    {
                        "required": [
                            "ccTLDs"
                        ]
                    }
                ],
                "dependentRequired": {
                    "associatedSites": [
                        "rationaleBySite"
                    ],
                    "serviceSites": [
                        "rationaleBySite"
                    ]
                }
            }
        }
    }
}

In RWS-Submission_Guidelines.md

• First schema under #set-submissions:

  • It does not have "contact" as "required".
  • For consistency, if you add the "oneOf" keyword to SCHEMA.json, it should also be added here.

• The example and the schema for the primary set does not contain "contact" : {"type": "string"}, anymore.

  • Is there a reason why contact is not required in the well-known file hosted at the primary domain?
  • It would likely make things easier if it were required in both places: canonical sets file on GitHub and hosted well-known primary files. If so, schemas and examples need to be updated to reflect this.

Other Misc

Under #set-level-technical-validation:

• The formatting of the example URLs/filenames with the back quotes is incorrect as well as some Markdown links.

• It does not seem that the 2 paths in bold in the following quote are supposed to be the same, right?

  The primary domain must serve a JSON file at /.well-known/related-website-set.json (Note: list entries merged before September 15th 2023 may serve their well-known file at /.well-known/related-website-set.json instead; however, any changes to those entries will require that the primary and all members of the set must be served at /.well-known/related-website-set.json like any other entry). The contents of the file must be identical to the submission. Each member domain must serve a JSON file at /.well-known/related-website-set.json. The contents of the file must name the primary domain. These files must be maintained for the duration of the domain’s inclusion in the set.

Best regards,

Yohan

[shuranhuang]

Hi Yohan, thank you for the feedback. We'll take a closer look and get back.