Guidelines
In order to make the Public Suffix List as current and accurate as possible, we request that TLD registries put in place processes to keep their section of the list current and accurate. This will make sure that all sites within their TLD continue to function fully within modern browsers, in terms of the site owners' ability to set cookies and so on.
In addition, owners of privately-registered domains who themselves issue subdomains to mutually-untrusting parties may wish to be added to the PRIVATE section of the list.
The general procedure to make changes is as follows:
- Carefully read about the list format to see how the list rules are defined.
- View the list, find your top-level domain (if present), and then check the rules already there for accuracy.
- If there are any additions, removals or amendments to be made, create a pull request for our Github repo.
Updates can be filed as either pull requests or issues, however a pull request is generally preferred. Pull requests are automatically checked by our test suite, and you can get an immediate feedback whether your submission contains some invalid rules that may cause the patch to be rejected.
Submissions are discussed either in the issue or in the pull request. Each submission requires validation, authentication and approval:
- Validation: the patch is validated to make sure the domains are acceptable and the patch follows the list format.
- Authentication: the patch is authenticated to make sure the changes are legit. The exact authorization procedure depends on the type of changes (see below).
- Approval: the patch is manually approved and merged. Generally, if the patch is validated and authenticated the approval is granted. However, in some cases we reject the request or encourage the submitter to alter the patch if we feel that the change will negatively impact the experience of the PSL consumers.
Our acceptance criteria are as follows:
-
We do not accept entries for use as DNS wildcards, such that e.g. 1-2-3-4.foo.tld resolves as IP address 1.2.3.4. This basically projects the security properties of the IP address space onto the domain name space, and we don't feel that is safe. IP addresses can be dynamically allocated to multiple mutually-untrusting parties; domain names generally are not.
-
We do not accept entries whose sole purpose is to circumvent Let's Encrypt rate limits. They have a form you can use.
These are Top Level Domains (or their direct, affiliated subordinates) that are delegated by the IANA, per ICP3, or new Top Level Domains with a contracting announcement from ICANN (these are in a special section within the ICANN Domains).
Changes here need to either come from a representative of the registry (authenticated in a similar manner to below) or be from public sources such as a registry website.
For private domains we need to confirm that the person submitting the request is an authorized representative of the domain owner. We will not accept patches submitted by third party users of the service.
Historically, we have been validating the authentication of the request by using the data in the whois response and sending an email to the domain owner. However, this approach doesn't scale very well. Here's the current validation list, in order of preference.
For each suffix included in the patch, add a corresponding DNS TXT record called _psl that contains the link to the PR.
For example, if you submit the following patch:
+// Company : http://www.example.com
+// Submitted by John Doe <[email protected]>
+alphaexample.com
+foo.betaexample.com
+*.gammaexample.comThen we expect to find the following DNS records (assuming the pull request ID is 100):
$ dig TXT _psl.alphaexample.com
https://github.com/publicsuffix/list/pull/100
$ dig TXT _psl.foo.betaexample.com
https://github.com/publicsuffix/list/pull/100
$ dig TXT _psl.gammaexample.com
https://github.com/publicsuffix/list/pull/100
In some circumstances, we may proceed with the email-based validation. However, the email must be clearly associated (generally in the public whois) with all the suffixes included in the pull request. If the pull request contains multiple suffixes and the email doesn't match all of them, then the entire pull request will be rejected.
For large companies we may require a mailing list such as [email protected] or administrative email, rather user-specific emails.
Follow this procedure to submit a change to the list.
Carefully read about the list format to see how the list rules are defined
View the list, find your top-level domain (if present), and then check the rules already there for accuracy. If you want to submit a private domain, go to the private domain section and find the appropriate position.
Read this page to properly understand the validation/authentication/approval requirements before submitting your request.
Prepare your change. Here's some rules to keep in mind:
-
Follow the repository conventions
-
For a IANA domain, update the header only if you have more relevant references.
-
For a new private domain section, keep the changeset sorted by Company/Product name within the
===BEGIN PRIVATE DOMAINS===and===END PRIVATE DOMAINS===block.For example, if your company is called "Example Company" and your want to list the suffixes
foobar.example, the position of the change will be determined by the alphabetical ordering of "Example Company" and notfoobar.example.Start the change with a header that includes the company information and the submitter email. You must be in control of the submitter email, as we may use it for the authentication. The email must belong to the entity that requests the change (note that you can only modify a private domain section if you are an authorized representative of the company).
// Example Company : https://example.com/ // Submitted by John Doe <[email protected]> foo.example.com -
Keep the list of suffix (if more than one) in alphabetical order. Sort first by the TLD, then the first label to the left of the TLD, and so forth. For example, the following is sorted by TLD first (
com,invalid,net,org,test), then within each TLD, sorted by the first label (example), then, for entries with more labels, each label is sorted, with shorter entries appearing first:beta.example.com alpha.beta.example.com // alpha.beta has more labels than beta, and thus comes second. delta.example.invalid // invalid sorts between com and net beta.example.net delta.example.net // delta sorts after beta, as example and net are the same charlie.example.org // org sorts after net, because sorting is by the right-most label, not the left-most alpha.example.test
Create a pull request with the requested changes.
It's recommended to clone and edit the change locally, as you will be able to test the changes before submitting the request. However, if you feel more comfortable, just use the GitHub in-browser editing feature to submit the pull request.
Please provide the following information:
- When submitting private domains, add a brief description of why you want the suffix(es) to be added to the list
- When submitting private domains, provide expected input/output to help us validate the correctness of the request
- When submitting IANA suffixes, provide the authoritative evidences supporting the change (if you work for the registry, please make that clear as well)
- Provide extra information useful for the PSL team to handle the pull request
If you make the changes locally, you can run the test suite before submitting the pull request. Make the change to the list, save the changes and run the following make command:
$ make test
Check the output for errors.
The tests are also run automatically using Travis CI when you create the pull request.
Please pay attention to the results of the tests. If the tests don't pass, amend your patch accordingly to the error messages.
Patches that don't pass the tests will be rejected.
After submission, please follow-up to the ticket and any correspondence email regarding questions, until the ticket is closed. Also make sure that the email you listed in the pull request is valid, as we may use it for validation or private follow ups.
Once the PSL update includes a submission, it is important to note that the PSL maintainers do not control the frequency of updates or inclusion of the change in the products or services that utilize the list, how the list is used there, and most importantly if that derivative work will include the update (or not).
Changes to the PSL may take time to percolate to clients, particularly those listed on the website. Given that some platforms have incorporated the PSL within the OS itself, updates may not happen until the next OS update.
In some circumstances, where the list is included or incorporated in some static manner by a library, product or service, one may see timing delays before seeing the change within those works. This can occur based upon schedules, product road maps and update cycles beyond the control or influence of the PSL maintainers / volunteers.
The PSL resource has no governance on how it is used, in whole, in part, or some modified version by derivative works. This includes how how vendors treat the addition and/or deletion of entries, or how they process updates information as the PSL gets updated.
The Public Suffix List is a list. It is entirely the decision and control of those who use or incorporate the list what they choose to do or not do. If there is a means to contact those parties who maintain or control the derivative works, they are the appropriate place to follow-up. It is constructive to allow for reasonable delay for the propagation of changes before doing so, regardless of the sense of urgency.