Fix documentation for deviceStorageDisclosureUrl

[mattpr]

currently deviceStorageDisclosureUrl is listed as optional....but based on the current changes it should not be optional going forward, right?

Also, I received an email from IAB saying that it is required that the json file is named deviceStorage.json...however this is not stated in the docs. The examples happen to use deviceStorage.json and the description for deviceStorageDisclosureUrl says: Location of vendor-hosted deviceStorage.json file....but it isn't obvious that there is requirement about file naming.

In fact when we set ours up we checked what url patterns other people were using and it is all over the map... so if this is important (not sure why you care about the file name when the absolute url is specified as part of the requirements)...it should be documented.

[anderagakura]

@mattpr At the top of the spec, we mention this page is deprecated. Within Transparency and Consent String with Global Vendor & CMP List Formats, you can see that deviceStorageDisclosureUrl is required.

currently deviceStorageDisclosureUrl is listed as optional....but based on the current changes it should not be optional going forward, right?

The document Vendor Device Storage & Operational Disclosures but not the deprecated one explains where the document is published "AdTech123 publishes this information at https://www.adtech123.com/path/to/deviceStorage.json, and provides this URL to the TCF during the registration process." and the process after. We care about the file name because we want a common place for us to check the vendors. For example, if a publisher discloses who is authorised to sell their inventory in a random file, the SSP and DSP would struggle to find it. Hopefully, the standard indicates to disclose them in a file name ads.txt. It's just a matter of standardisation.

Also, I received an email from IAB saying that it is required that the json file is named deviceStorage.json...however this is not stated in the docs. The examples happen to use deviceStorage.json and the description for deviceStorageDisclosureUrl says: Location of vendor-hosted deviceStorage.json file....but it isn't obvious that there is requirement about file naming.

In fact when we set ours up we checked what url patterns other people were using and it is all over the map... so if this is important (not sure why you care about the file name when the absolute url is specified as part of the requirements)...it should be documented.

[mattpr]

Thanks. The email from IAB about us not having a standard filename cited the page I cited (https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20Device%20storage%20duration%20and%20access%20disclosure.md#required-information-and-json-structure).

I didn't scroll to the top and read the whole page, so thanks for pointing out that this page is no longer relevant.

On the link you sent I do see that deviceStorageDisclosureUrl is required. However the example right below that is:

"deviceStorageDisclosureUrl": "https://vendorname.com/path/to/deviceAndOperationalDisclosures.json"

...which is obviously not deviceStorage.json.

This page has specs for the json contents of the file but no requirements for the URL.

AdTech123 publishes this information at https://www.adtech123.com/path/to/deviceStorage.json, and provides this URL to the TCF during the registration process.

As I read it, this is an example, not a requirement/spec just to explain that the spec-following json should be included in a file hosted at a URL and that absolute URL is provided to IAB during registration process.

Under Serving the JSON Resource you have the following...

Because CMPs must load the JSON file in the browser, Vendors must enable Cross-Origin Resource Sharing (CORS) at the location servicing the URL. Vendors must respond with the appropriate content-type header (application/json) and cache -control directives so that CMPs are accessing the latest content when fetching from users’ browsers. The URL need not be served by the Vendor’s company domain. It could be served from a CDN.

So as far as I can see, the only requirements are:

• providing a deviceStorage JSON URL is now required according to the updated doc.
• the absolute URL needs to be provided to IAB during the registration process
• the webserver serving the json should use appropriate cache control, enable CORS and serve the file correctly (appropriate content-type header).
• the contents of the JSON file should comply with the technical spec

For example, if a publisher discloses who is authorised to sell their inventory in a random file, the SSP and DSP would struggle to find it. Hopefully, the standard indicates to disclose them in a file name ads.txt. It's just a matter of standardisation.

I'll argue that is totally different. ads.txt is at a well known (although not /.well-known/) and predictable location in the same way that robots.txt is. ads.txt is a publisher-side feature and so you have predictable domains (any domain you come across displaying ads on the internet). A content domain either has an ads.txt or doesn't (just like with robots.txt). You don't need to know the domain ahead of time, you come across a domain and can check if it has an ads.txt or not because it has to be at the root of the domain (/ads.txt).

Vendor deviceStorage on the other hand...you don't have a predictable domain and there is nothing in the spec about serving the file from a well known path (e.g. web root: /deviceStorage.json).

We care about the file name because we want a common place for us to check the vendors.

The spec says

The URL need not be served by the Vendor’s company domain. It could be served from a CDN.

...so the domain isn't predictable.

Neither is the path (could be /deviceStorage.json or /foo/bar/deviceStorage.json...because the spec doesn't require anything in particular and uses examples like /path/to/deviceStorage.json).

Without knowing both the domain and the path where the json file is hosted, knowing the name of the json file is useless. This is the reason we have to provide an absolute URL and the reason why there is zero value is having a standard name for the json file itself.

A common place for you to check the vendors is not part of the spec. The spec is that the vendors provide an absolute URL to a compliant JSON file. That absolute url either returns an in-spec json or doesn't and that appears to be the scope of these requirements.

Nevertheless if IAB wants to make standard filenames a requirement, it isn't a problem...but the docs should be updated to reflect that so we don't have to revisit these topics over and over. Thanks!

[Atachi]

Second the issue.

If the file name for whatever reason is supposed to be fixed, it should be mentioned explicitly.

Getting that email was rather confusing as the limitation makes no sense besides an "incorrect" validation script that uses different assumptions than what is stated in the specs.

I'd even argue that this limitation prevents having multiple deviceStorage definitions for multiple scopes on the same domain without having to use multiple paths.

---

Edit: You may want to update your email template to reference the current documentation, not the deprecated one, as well.

[HeinzBaumann]

Since we require the full URL to be registered, it doesn't make a lot of sense to require a notation or fixed naming of the file or the path. Doesn't it? I think we should update the spec and the validation script accordingly IMO.

[jdelhommeau]

I agree with @HeinzBaumann , no need for name standardization if we ask for full URL. Lets update the spec and email to reflect that more clearly.

[anderagakura]

Before making any move let's discuss via mail. I keep you all updated.

[anderagakura]

I close this issue because it's fixed with #324