Add draft of schema file #2

radishmouse · 2024-05-02T18:18:37Z

Closes #1

The new schema.json includes the fields mentioned in the tech spec as well as:

descriptions of each field
a list of required fields

Please let me know if anything is missing or needs improvement!

Update: now includes a version of the schema generated by the pydantic model (from #5).
With the exception of the dependantRequired key , it is equivalent to the schema.json introduced by this PR.

MelissaAutumn · 2024-05-02T18:21:37Z

cc @freaktechnik & @vDeo

Do you two have any questions, or concerns about this spec?

radishmouse · 2024-05-02T21:38:04Z

I've got a more fields to add (thankfully, @Sancus alerted me to the missing fields), but won't be able to address until tomorrow

freaktechnik

I just had a thought: we can handle localization with the locale filtering, so we have one of these objects per locale and just filter them.

freaktechnik · 2024-05-03T11:06:40Z

schema.json

+        "start_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp after which Thunderbird will show the event after startup."
+        },
+        "end_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp after which Thunderbird will never show the event, even if it has never been shown to the user."
+        },


I assume these will be ...T...Z timestamps? From the json schema docs I could find they didn't specify that it should include a timezone.

I think that including a timezone should be fine?
I couldn't find a validator that actually checked if a date-time string field was formatted correctly.

(The validators said everything was 👍 whether I put in a timestamp with/without a timezone...and even the string "this is not a timestamp")

This should always be UTC for consistency when we are publishing events. It's fine if the client is able to handle other time zones, but not required.

freaktechnik · 2024-05-03T11:09:18Z

schema.json

+        },
+        "description": {
+          "type": "string",
+          "description": "A short paragraph that can contain HTML and will be displayed in the Thunderbird UI."


I think we should limit the allowed HTML so we can sanitize it and display it confidently. Obviously we can do this unilaterally in the client anyway, but maybe we'd want to define that somewhere.

schema.json

radishmouse · 2024-05-03T15:33:56Z

.

I just had a thought: we can handle localization with the locale filtering, so we have one of these objects per locale and just filter them.

@MelissaAutumn suggested something similar: maybe when the client requests the notifications, it sends a locale string as a parameter. That way, the server only sends back the locale-specific notifications.

freaktechnik · 2024-05-03T15:31:51Z

schema.json

+          "exclude": {
+            "$ref": "#/definitions/profile"
+          },
+          "include": {
+            "$ref": "#/definitions/profile"
+          }


Should these be arrays of profile in case we want to target specific combinations? I don't love the arrays of arrays structure this would lead to though.

🤔 making them arrays of profile is probably the best way to do combinations. But yeah, could be annoying to process on the client.

schema.json

freaktechnik · 2024-05-03T15:51:33Z

Mel suggested something similar: maybe when the client requests the notifications, it sends a locale string as a parameter. That way, the server only sends back the locale-specific notifications.

Right, but that would mean you're doing actual work on the server side. As I had mentioned, we should easily be able to do an URL similar to what the release notes have: https://searchfox.org/comm-central/rev/c04464d92274c9d2b8ec036d47b0c664adf1a45f/mail/app/profile/all-thunderbird.js#127

…S "other"

freaktechnik · 2024-05-03T16:34:40Z

schema.json

+        "channels": {
+          "type": "array",
+          "items": {
+            "enum": ["esr", "release", "beta", "daily"],


I think this would be default for builds that aren't on any channel, like local builds or possibly other "unbranded" builds. The SoW doesn't have any mention of that, just trying to think of all the permutations of what we might encounter in the wild.

That's a good point. @Sancus, any objection to sending notifications to any/all builds by specifying default?

Not sure it was clear, I meant the string default as enum value, so "default"

E: Nevermind all that stuff. On further examination, there is actually a decent number of folks on the default channel, so yeah it makes sense to include that here. I'm guessing this is used by some distros for their package managed builds. It might be useful to target.

There ARE a lot of other minor channels but I don't think we need targeting for them in v1.

To target everybody NOT on a major channel I would still go with a blacklist.

👍

Question: Should I add a "denylist" to the schema? (and maybe change "targeting" to "allowlist"?)

Isn't that what exclude and include do?

hahahaha yes.
😂

Sancus · 2024-05-16T01:30:54Z

schema.json

+          "type": "array",
+          "items": {
+            "enum": [
+              "windows",


I think these values should probably be the ones used by Thunderbird itself. That was my intent for all the targeting filters, that they mirror the values used internally in the client so Thunderbird doesn't need some crazy remapping scheme in comm-central.

I'm not sure what all possible values of %OS% are in Thunderbird. I think the major three are WINNT, Darwin, and Linux though. @jfx2006 might know or know where you can find lists of these things.

I've been looking at https://searchfox.org/mozilla-central/source/toolkit/modules/AppConstants.sys.mjs since that's what I get at runtime.

Ah, the URL formatter uses appinfo: https://searchfox.org/mozilla-central/source/toolkit/components/urlformatter/URLFormatter.sys.mjs#71-136, which uses OS_TARGET: https://searchfox.org/mozilla-central/source/toolkit/xre/nsAppRunner.cpp#1217, so that'd be the values you're talking about.

I've been looking at https://searchfox.org/mozilla-central/source/toolkit/modules/AppConstants.sys.mjs since that's what I get at runtime.

Ah, if it's easy for you to get that at runtime then nevermind, use that. Seems fine to me.

If we'd want to match it that'd still mean "win" and "macosx" as values though.

Yeah definitely match, it will avoid having to maintain mappings on the client side.

👍 makes sense! I've updated those two enum values to match AppConstants.sys.mjs

radishmouse · 2024-06-07T17:32:55Z

@freaktechnik @Sancus The changes introduced by #5 include a command for generating a JSON schema from a pydantic model.

The pydantic model includes all the same enum values and constraints as the JSON schema in this PR.

Would it be reasonable to close this PR in favor of a generated schema file?
Alternatively, we could create another ticket to test the generated JSON schema more thoroughly.

MelissaAutumn · 2024-06-07T19:28:46Z

@freaktechnik @Sancus The changes introduced by #5 include a command for generating a JSON schema from a pydantic model.

The pydantic model includes all the same enum values and constraints as the JSON schema in this PR.

Would it be reasonable to close this PR in favor of a generated schema file? Alternatively, we could create another ticket to test the generated JSON schema more thoroughly.

Hey @radishmouse can you commit a current copy of that schema to repo for reference? And a general note it is missing the dependantRequired key (#7) but is otherwise matching.

radishmouse · 2024-06-07T20:22:07Z

@MelissaAutumn generated schema added to this PR

Also, I updated the PR description making it clear that the generated schema is missing the dependantRequired key (but otherwise matches).

freaktechnik · 2024-06-10T09:10:17Z

I assume all the optional keys being nullable is a side effect of what it's being generated from?

I think the manually written schema currently captures some less formal conventions on the interface, which the generated schema doesn't document.

radishmouse · 2024-07-11T22:15:31Z

It sounds like the manually written schema is preferred. I'll merge this PR and update the JSON validation GH action to use it.

Add draft of schema file

4c43386

Makes CTA dependent on URL

5ffbd76

freaktechnik reviewed May 3, 2024

View reviewed changes

radishmouse added 2 commits May 3, 2024 10:53

Updates version of schema, adjusting syntax for array

ca55183

Add targeting

604a09c

freaktechnik reviewed May 3, 2024

View reviewed changes

Per PR feedback: text tweak, include/exclude arrays of profile, add O…

97799b0

…S "other"

freaktechnik reviewed May 3, 2024

View reviewed changes

radishmouse added 2 commits May 14, 2024 16:18

Update description to indicate UTC timestamps

e0653bc

Add "default" channel

dc625a9

Sancus reviewed May 16, 2024

View reviewed changes

Match OS names from AppConstants.sys.mjs

caf5d02

Add version of schema auto-generated by pydantic model

566caa4

radishmouse merged commit f340d58 into main Jul 11, 2024

radishmouse deleted the features/1-json-schema branch July 11, 2024 22:16

This was referenced Jul 11, 2024

Use manually written JSON schema instead of generated one #11

Closed

Updates gh action to use manually written JSON schema #12

Merged

radishmouse mentioned this pull request Sep 16, 2024

Capture less formal conventions in generated schema #19

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add draft of schema file #2

Add draft of schema file #2

radishmouse commented May 2, 2024 •

edited

Loading

MelissaAutumn commented May 2, 2024

radishmouse commented May 2, 2024

freaktechnik left a comment

freaktechnik May 3, 2024

radishmouse May 3, 2024

Sancus May 14, 2024

freaktechnik May 3, 2024

radishmouse commented May 3, 2024

freaktechnik May 3, 2024

radishmouse May 3, 2024

freaktechnik commented May 3, 2024

freaktechnik May 3, 2024

radishmouse May 3, 2024

freaktechnik May 3, 2024 •

edited

Loading

Sancus May 14, 2024 •

edited

Loading

radishmouse May 14, 2024

freaktechnik May 14, 2024

radishmouse May 14, 2024

Sancus May 16, 2024 •

edited

Loading

freaktechnik May 16, 2024

freaktechnik May 16, 2024

Sancus May 16, 2024

freaktechnik May 17, 2024

Sancus May 18, 2024

radishmouse May 20, 2024

radishmouse commented Jun 7, 2024 •

edited

Loading

MelissaAutumn commented Jun 7, 2024 •

edited by radishmouse

Loading

radishmouse commented Jun 7, 2024

freaktechnik commented Jun 10, 2024 •

edited

Loading

radishmouse commented Jul 11, 2024

Add draft of schema file #2

Add draft of schema file #2

Conversation

radishmouse commented May 2, 2024 • edited Loading

MelissaAutumn commented May 2, 2024

radishmouse commented May 2, 2024

freaktechnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

radishmouse commented May 3, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

freaktechnik commented May 3, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

freaktechnik May 3, 2024 • edited Loading

Choose a reason for hiding this comment

Sancus May 14, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sancus May 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

radishmouse commented Jun 7, 2024 • edited Loading

MelissaAutumn commented Jun 7, 2024 • edited by radishmouse Loading

radishmouse commented Jun 7, 2024

freaktechnik commented Jun 10, 2024 • edited Loading

radishmouse commented Jul 11, 2024

radishmouse commented May 2, 2024 •

edited

Loading

freaktechnik May 3, 2024 •

edited

Loading

Sancus May 14, 2024 •

edited

Loading

Sancus May 16, 2024 •

edited

Loading

radishmouse commented Jun 7, 2024 •

edited

Loading

MelissaAutumn commented Jun 7, 2024 •

edited by radishmouse

Loading

freaktechnik commented Jun 10, 2024 •

edited

Loading