[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
I wouldn't be concerned about extra pages. If you feel comfortable with this, please submit the PR. It looks good to me. -- Alex Brotman Sr. Engineer, Anti-Abuse & Messaging Policy Comcast > -Original Message- > From: Daniel K. > Sent: Thursday, January 9, 2025 4:18 PM > To: dmarc@ietf.org > Subject: [dmarc-ietf] Re: Proposal for new prose describing the aggregate > report XML > > On 1/9/25 18:44, Alessandro Vesely wrote: > > How about this? > > > > > +==+==++=+ > > | Element name | Required | Unique | Content | > > > > > +==+==++=+ > > Unexpectedly, this did not cause any extra pages to be required for the > output: > > https://urldefense.com/v3/__https://ietf.vendo.no/draft-ietf-dmarc- > aggregate-reporting-table-four-col.txt__;!!CQl3mcHX2A!A9- > KvsoA4QIstU8WOW9mhpMO8BAfdZquQgiR2WWUZiyRWDcyqfZ_1J91PXBnx > AMnyw3cCcCiDymhkxYF6v4k$ > > Given that only 4 of the 13 tables have one element each that can repeat, I > think it's overkill to add this as a separate column. > > For consistency, I discarded the option of omitting the column from the tables > that only have "Yes" as the value for all elements. > > > Daniel K. > > ___ > dmarc mailing list -- dmarc@ietf.org > To unsubscribe send an email to dmarc-le...@ietf.org ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 1/9/25 18:44, Alessandro Vesely wrote: > How about this? > > +==+==++=+ > | Element name | Required | Unique | Content | > +==+==++=+ Unexpectedly, this did not cause any extra pages to be required for the output: https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-table-four-col.txt Given that only 4 of the 13 tables have one element each that can repeat, I think it's overkill to add this as a separate column. For consistency, I discarded the option of omitting the column from the tables that only have "Yes" as the value for all elements. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Wed 08/Jan/2025 23:58:27 +0100 Daniel K. wrote: +==+==+=+ | Element name | Required | Content | +==+==+=+ +==+===+=+ | Element name | Req'd | Content | +==+===+=+ The name is more explicit and wider. The cost is one or two pages extra compared to the "#" alternative above. For these two, the value of the 'Required' column may be: No: OPTIONAL Yes: REQUIRED No *: 0 or more elements Yes *: 1 or more elements How about this? +==+==++=+ | Element name | Required | Unique | Content | +==+==++=+ Best Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 1/8/25 21:30, Brotman, Alex wrote: > If you think this is ready, I will merge a PR and release a new version after > that. I think it's almost ready. I have one or two points I'd like to fix, but I haven't worked on it since the email you responded to was written. The biggest issue, one that I think need author guidance, is which of the table formats to use. There have been many suggestions on the layout of the tables, specially for the column that shows the number of allowed elements. See my previous mail to see the tables in all their glory, but it boils down to the space used: +==+===+=+ | Element name | # | Content | +==+===+=+ The short column name is beneficial because it leaves more space for the content column. The value of the '#' column may be: " " (empty): OPTIONAL element "R": REQUIRED element "*": 0 or more elements "+": 1 or more elements "*" and "+" can be understood like in regexp syntax. +==+==+=+ | Element name | Required | Content | +==+==+=+ +==+===+=+ | Element name | Req'd | Content | +==+===+=+ The name is more explicit and wider. The cost is one or two pages extra compared to the "#" alternative above. For these two, the value of the 'Required' column may be: No: OPTIONAL Yes: REQUIRED No *: 0 or more elements Yes *: 1 or more elements I also wrote about using "0..n" and "1..n" as synonyms for "No *" and "Yes *", but I think that is less clear. If we do not want to use notation to signal an unbounded amount of elements, we can add something like the following immediately after the table: The maximum number of "foobar" elements is unbounded. I think it's time for the draft author to make a decision, and I'll adjust accordingly. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
If you think this is ready, I will merge a PR and release a new version after
that.
--
Alex Brotman
Sr. Engineer, Anti-Abuse & Messaging Policy
Comcast
> -Original Message-
> From: Daniel K.
> Sent: Friday, January 3, 2025 7:33 PM
> To: dmarc@ietf.org
> Subject: [dmarc-ietf] Re: Proposal for new prose describing the aggregate
> report
> XML
>
> On 1/3/25 16:58, Alessandro Vesely wrote:
> > On Thu 02/Jan/2025 05:16:26 +0100 Daniel K. wrote:
> >> On 12/30/24 19:40, Daniel K. wrote:
> >>> Alex requested min/max count of the elements, REQUIRED / OPTIONAL
> >>> could be replaced by one of "0..1", "0..n", "1..1", "1..n" that
> >>> nicely conveys both min/max and requirement level, albeit a bit less
> >>> visually distinctive.
> >>
> >> I took a page from the regexp world, so in addition to "R" for
> >> required, I introduced "+" for "one or more" and "*" for "zero or more".
> >
> > I still think a yes/no under a "REQUIRED" column header would be
> > easier to grok, even if it takes up more horizontal space. However, I
> > like the effect of the tables being distributed into their respective
> > sections.
>
> The price is two extra pages, compared to the compact version.
>
> https://urldefense.com/v3/__https://ietf.vendo.no/draft-ietf-dmarc-aggregate-
> reporting-table-wide-
> col.txt__;!!CQl3mcHX2A!CMqzoQ2U0EqfCZTbVVjZyXY3yWCDZ0wh9rnb_9vBEvdv
> uIj4QLNh2CYROnWYhHwsSpqU2BVbkznu-BLMAH5z$
>
> Using "Req'd" as the table header get one of those pages back.
>
> https://urldefense.com/v3/__https://ietf.vendo.no/draft-ietf-dmarc-aggregate-
> reporting-table-medium-
> col.txt__;!!CQl3mcHX2A!CMqzoQ2U0EqfCZTbVVjZyXY3yWCDZ0wh9rnb_9vBEvdv
> uIj4QLNh2CYROnWYhHwsSpqU2BVbkznu-DoJVLHq$
>
> The support for communicating which elements having no limit to their number
> are also lost, unless we put in '0..n', '1..n', 'No *', 'Yes *', or something
> ABNF-like
> ('*', '1*') in the yes/no column for those few special elements. Another
> option is
> of course to spell it out after the table, see below.
>
> Here are the variants, for comparison.
>
>+==+===+=+
>| Element name | # | Content |
>+==+===+=+
>| dkim | * | DKIM authentication result, |
>| | | see Section 2.1.1.11. |
>+--+---+-+
>| spf | | SPF authentication result, |
>| | | see Section 2.1.1.12. |
>+--+---+-+
>
>+==+==+=+
>| Element name | Required | Content |
>+==+==+=+
>| dkim | No | DKIM authentication result, |
>| | | see Section 2.1.1.11. |
>+--+--+-+
>| spf | No | SPF authentication result, |
>| | | see Section 2.1.1.12. |
>+--+--+-+
>
>+==+===+=+
>| Element name | Req'd | Content |
>+==+===+=+
>| dkim | No| DKIM authentication result, |
>| | | see Section 2.1.1.11. |
>+--+---+-+
>| spf | No| SPF authentication result, |
>| | | see Section 2.1.1.12. |
>+--+---+-+
>
> The maximum number of "dkim" elements is unbounded.
>
>
> Daniel K.
>
> ___
> dmarc mailing list -- dmarc@ietf.org
> To unsubscribe send an email to dmarc-le...@ietf.org
___
dmarc mailing list -- dmarc@ietf.org
To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 1/3/25 16:58, Alessandro Vesely wrote:
> On Thu 02/Jan/2025 05:16:26 +0100 Daniel K. wrote:
>> On 12/30/24 19:40, Daniel K. wrote:
>>> Alex requested min/max count of the elements, REQUIRED / OPTIONAL could
>>> be replaced by one of "0..1", "0..n", "1..1", "1..n" that nicely
>>> conveys both min/max and requirement level, albeit a bit less visually
>>> distinctive.
>>
>> I took a page from the regexp world, so in addition to "R" for required,
>> I introduced "+" for "one or more" and "*" for "zero or more".
>
> I still think a yes/no under a "REQUIRED" column header would be easier to
> grok, even if it takes up more horizontal space. However, I like the effect
> of
> the tables being distributed into their respective sections.
The price is two extra pages, compared to the compact version.
https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-table-wide-col.txt
Using "Req'd" as the table header get one of those pages back.
https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-table-medium-col.txt
The support for communicating which elements having no limit to their
number are also lost, unless we put in '0..n', '1..n', 'No *', 'Yes *',
or something ABNF-like ('*', '1*') in the yes/no column for those few
special elements. Another option is of course to spell it out after the
table, see below.
Here are the variants, for comparison.
+==+===+=+
| Element name | # | Content |
+==+===+=+
| dkim | * | DKIM authentication result, |
| | | see Section 2.1.1.11. |
+--+---+-+
| spf | | SPF authentication result, |
| | | see Section 2.1.1.12. |
+--+---+-+
+==+==+=+
| Element name | Required | Content |
+==+==+=+
| dkim | No | DKIM authentication result, |
| | | see Section 2.1.1.11. |
+--+--+-+
| spf | No | SPF authentication result, |
| | | see Section 2.1.1.12. |
+--+--+-+
+==+===+=+
| Element name | Req'd | Content |
+==+===+=+
| dkim | No| DKIM authentication result, |
| | | see Section 2.1.1.11. |
+--+---+-+
| spf | No| SPF authentication result, |
| | | see Section 2.1.1.12. |
+--+---+-+
The maximum number of "dkim" elements is unbounded.
Daniel K.
___
dmarc mailing list -- dmarc@ietf.org
To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Thu 02/Jan/2025 05:16:26 +0100 Daniel K. wrote: On 12/30/24 19:40, Daniel K. wrote: Alex requested min/max count of the elements, REQUIRED / OPTIONAL could be replaced by one of "0..1", "0..n", "1..1", "1..n" that nicely conveys both min/max and requirement level, albeit a bit less visually distinctive. I took a page from the regexp world, so in addition to "R" for required, I introduced "+" for "one or more" and "*" for "zero or more". I still think a yes/no under a "REQUIRED" column header would be easier to grok, even if it takes up more horizontal space. However, I like the effect of the tables being distributed into their respective sections. Keep up the good work Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 1/2/25 12:52, Alessandro Vesely wrote: > On Thu 02/Jan/2025 00:15:19 +0100 Daniel K. wrote: >> >> - >> + > > That change was by Matt Wander in 2021 on gdoc > https://docs.google.com/document/d/1Fh18iswRu4WJxnN6LBPIpVBncwhfJODOQxoeYH__Z-Q/ > > It looked like a harmless simplification, given the nature of those fields. Thanks, I somehow bungled the arguments to interdiff, so I quoted the reverse of the actual change that was from "sequence" => "all". I agree with the rationale given by Matt. "error" was later put back, but with maxOccurs="1" which is compatible with "all". >> >> - >> + > > This has always been unordered, AFAIK. Yes, but it is now "sequence". The same argument holds for RowType (no unbounded elements), and I will add a commit changing it back to "all", the way ut was in RFC7489. > The only reason I can think of is to ease poor parsers. As they've always > been , should we check if report generators actually follow the order > given in the schema? As long as we loosen the restrictions, I don't think it matters. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Thu 02/Jan/2025 00:15:19 +0100 Daniel K. wrote: On 12/30/24 19:40, Daniel K. wrote: Doing this work I have noted a few inconsistencies which I'll raise when I have pondered a little bit more, and written something intelligible about it. Alessandro, in commit: 7a993a2 xsd and xml examples The following is hiding among the white-space changes: - + restricting the contents to now be in the specified order, and That change was by Matt Wander in 2021 on gdoc https://docs.google.com/document/d/1Fh18iswRu4WJxnN6LBPIpVBncwhfJODOQxoeYH__Z-Q/ It looked like a harmless simplification, given the nature of those fields. - + relaxing the requirements for a previously ordered list of elements. This has always been unordered, AFAIK. Do you remember if this was deliberate, and if so, what the rationale was? I'd like to have both be of the "" type, as I see no reason the report_metadata contents are required to be in a fixed order. The only reason I can think of is to ease poor parsers. As they've always been , should we check if report generators actually follow the order given in the schema? Best Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/30/24 19:40, Daniel K. wrote: > Alex requested min/max count of the elements, REQUIRED / OPTIONAL could > be replaced by one of "0..1", "0..n", "1..1", "1..n" that nicely > conveys both min/max and requirement level, albeit a bit less visually > distinctive. I took a page from the regexp world, so in addition to "R" for required, I introduced "+" for "one or more" and "*" for "zero or more". > The ordered-ness of sibling elements is trickier to express in a compact > way, and I don't have a solution for it. > > In the multiple tables version it could be written before the table, and > not be in the table itself. I opted to just spell it out: The elements in this table MUST appear in the order listed. The table version did not turn out terrible. I've removed some content from the table rows and put the text below the tables. I think the readability improved, and by a stroke of luck none of the tables span a page break any more. Anyway, here's the result, one render for the list version, and one for the table version, there are .html versions as well. https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-list.txt https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-table.txt You can even see them side by side, thank you diffsite: https://diffsite.vendo.no/?url1=https%3A%2F%2Fietf.vendo.no%2Fdraft-ietf-dmarc-aggregate-reporting-list.txt&url2=https%3A%2F%2Fietf.vendo.no%2Fdraft-ietf-dmarc-aggregate-reporting-table.txt The WIP is here: https://github.com/d-javu/draft-ietf-dmarc-aggregate-reporting/tree/wip_prose There's a mix of things there, but the meat is after the "Local changes" commits, if you want to see more details. For my own sanity, I started by creating the list version from the current text, then filling in with missing pieces and comments from the XSD. I then made some edits and finally turned that result into the table version. If either version gets a thumbs up for form, I can clean up the patches and prepare a proper pull request. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/30/24 19:40, Daniel K. wrote: > Doing this work I have noted a few inconsistencies which I'll raise when > I have pondered a little bit more, and written something intelligible > about it. Alessandro, in commit: 7a993a2 xsd and xml examples The following is hiding among the white-space changes: - + restricting the contents to now be in the specified order, and - + relaxing the requirements for a previously ordered list of elements. Do you remember if this was deliberate, and if so, what the rationale was? I'd like to have both be of the "" type, as I see no reason the report_metadata contents are required to be in a fixed order. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Mon 30/Dec/2024 17:25:34 +0100 Mark E. Mallett wrote: I simply wonder why there is order needed in some (or all) elements. Why does it matter that "row" and "identifiers" and "auth_results" appear in fixed order? I realize that the corresponding xs:sequence tags occur in RFC7489, and perhaps this wonderment was addressed in old discussions, so maybe never mind. But in my naivete I don't see the reason. (Maybe the reason could be stated.) Changing the order may break some parser, methinks. Robust XML libraries won't choke, but code simply matching field names may. Best Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Mon 30/Dec/2024 20:40:12 +0100 Daniel K. wrote: On 12/30/24 16:25, Mark E. Mallett wrote: On Sun, Dec 29, 2024 at 12:13:59AM +, Daniel K. wrote: The tables also lose information on where the order of elements is mandated by the XSD. There's no room for more columns to describe it. If extra effort (like side notes) are needed to accomodate a table, that makes the table less attractive (to me). OTOH maybe the "required" column could be turned into "notes" or some such thing, with there being notes to indicate "required" or "optional" or "ordered." There are many problems with tables. * The markdown syntax mandates that one row is on a single line, that makes it a bit cumbersome to edit if you have a lot of content. * Lack of control over formatting, especially column widths. * Lack of horizontal space. That is a markdown limitation. Xml2rfc allows much the same attributes as html (rowspan, colspan, ...) An attempt at it failed, see e.g. https://github.com/mmarkdown/mmark/pull/153 Would a new issue to signal our wish for better tables be fair? Best Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
It appears that Daniel K. said: >On 12/30/24 16:25, Mark E. Mallett wrote: >> On Sun, Dec 29, 2024 at 12:13:59AM +, Daniel K. wrote: >>> The tables also lose information on where the order of elements is >>> mandated by the XSD. There's no room for more columns to describe it. >> >> If extra effort (like side notes) are needed to accomodate a table, that >> makes the table less attractive (to me). OTOH maybe the "required" column >> could be turned into "notes" or some such thing, with there being notes >> to indicate "required" or "optional" or "ordered." > >There are many problems with tables. > >* The markdown syntax mandates that one row is on a single line, that >makes it a bit cumbersome to edit if you have a lot of content. > >* Lack of control over formatting, especially column widths. > >* Lack of horizontal space. Keep in mind that the editors at the RPC do the final edits and formatting tweaks. So long as it is clear what your table is supposed to show, don't worry about making it look beautiful. This stuff is complicated no matter how we present it so I think a table is as good an option as any. R's, John ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/30/24 16:25, Mark E. Mallett wrote: > On Sun, Dec 29, 2024 at 12:13:59AM +, Daniel K. wrote: >> The tables also lose information on where the order of elements is >> mandated by the XSD. There's no room for more columns to describe it. > > If extra effort (like side notes) are needed to accomodate a table, that > makes the table less attractive (to me). OTOH maybe the "required" column > could be turned into "notes" or some such thing, with there being notes > to indicate "required" or "optional" or "ordered." There are many problems with tables. * The markdown syntax mandates that one row is on a single line, that makes it a bit cumbersome to edit if you have a lot of content. * Lack of control over formatting, especially column widths. * Lack of horizontal space. Alex requested min/max count of the elements, REQUIRED / OPTIONAL could be replaced by one of "0..1", "0..n", "1..1", "1..n" that nicely conveys both min/max and requirement level, albeit a bit less visually distinctive. The ordered-ness of sibling elements is trickier to express in a compact way, and I don't have a solution for it. In the multiple tables version it could be written before the table, and not be in the table itself. > But that's not what prompted a comment either. I simply wonder why there is > order needed in some (or all) elements. Why does it matter that "row" and > "identifiers" and "auth_results" appear in fixed order? I realize that the > corresponding xs:sequence tags occur in RFC7489, and perhaps this wonderment > was addressed in old discussions, so maybe never mind. But in my naivete > I don't see the reason. (Maybe the reason could be stated.) I'm new here as well, and I can only speculate as to the true reason. One likely possibility can be that it is to make it possible or easier for streaming XML parsers to be used. If you implement your processor that way and put data into a database structured with tables for a report and records, it is much easier if you know the metadata comes before the "record" elements. Doing this work I have noted a few inconsistencies which I'll raise when I have pondered a little bit more, and written something intelligible about it. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Sun, Dec 29, 2024 at 12:13:59AM +, Daniel K. wrote: > 3.1.1.1. Prose version - must contain removed > > Basically the same as before, but with the 'Must contain' introduction > removed. That wording certainly got a bit repetitive. > > > 3.1.1.2. Multiple tables version > 3.1.1.3. Single table version > 3.1.1.4. Single table version 2 I think the prose version is fairly clear and gives the most opportunity for extra description if needed. Of the tables I prefer 3.1.1.4 (with the dots). This is what prompted me to reply, though: > The tables also lose information on where the order of elements is > mandated by the XSD. There's no room for more columns to describe it. If extra effort (like side notes) are needed to accomodate a table, that makes the table less attractive (to me). OTOH maybe the "required" column could be turned into "notes" or some such thing, with there being notes to indicate "required" or "optional" or "ordered." But that's not what prompted a comment either. I simply wonder why there is order needed in some (or all) elements. Why does it matter that "row" and "identifiers" and "auth_results" appear in fixed order? I realize that the corresponding xs:sequence tags occur in RFC7489, and perhaps this wonderment was addressed in old discussions, so maybe never mind. But in my naivete I don't see the reason. (Maybe the reason could be stated.) -mm- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
If we were to go with the table (I suppose it could go with the bullet version also), why not have the min/max count in the table as well as other items? It could be done with shorthand notation. I think I prefer the table version, even with the variable width tables. -- Alex Brotman Sr. Engineer, Anti-Abuse & Messaging Policy Comcast > -Original Message- > From: Daniel K. > Sent: Sunday, December 29, 2024 3:40 PM > To: dmarc@ietf.org > Subject: [dmarc-ietf] Re: Proposal for new prose describing the aggregate > report XML > > On 12/29/24 19:06, Alessandro Vesely wrote: > > On Sun 29/Dec/2024 01:13:59 +0100 Daniel K. wrote: > >> I opted to remove the words [...] > > > > There are still several "must contain", though. In particular, mind > > "A single report MUST contain data for one policy configuration.", which has > changed. > > This is inherited from the old version. I tried hard to preserve all the > information, rearrange the previous prose into something new, and expanding > it to be complete. > > I intend to do incremental changes as separate commits, so that it stands out > properly and eases reviewing. > > Do not pay too much attention to all the details, as I'm primarily exploring > the > layout at this point. In particular, the text of the bullet style version may > not be > exactly the same as the text in the table versions. > > > > Perhaps somewhere we should say that "count" is the only non-key field. > > I'll collect it for later. > > > >> 3.1.1.2. Multiple tables version > > > > This is the one I like better. It allows each table to be furnished > > with comments common to various fields, e.g. the begin and end ind > date_range. > > What I dislike about this alternative is the variable width of the different > tables. > Maybe there's some magic that can be applied to the syntax that avoids it, or > maybe it doesn't stand out so much if it is rearranged as you suggest below. > > > > Possibly, each table could be moved to the specific section; for > > example, (the remaining part of) Handling Domains in Reports could > > stay together with the identifier table. > > I don't think I want to spread it around too much, but I'll try it out. > > > >> 3.1.1.3. Single table version > >> 3.1.1.4. Single table version 2 > > > > OTOH, the REQUIRED/ OPTIONAL column is better recognizable. We could > > give up capital case in the table versions, and replace those values with > yes/no. > > I'll try to put just an 'R' by the required elements. Should be shorter, at > least, > but also more visible, as the optional elements will not have a marker. > > > >> At the end of 3.1.1.3, there's a few paragraphs that did not quite > >> fit in a particular place in the table. I don't think it fits > >> perfectly at the end either. > > > > > > They may make better sense in the multiple tables version. > > Indeed, they are already close to the relevant tables there. > > > >> The tables also lose information on where the order of elements is > >> mandated by the XSD. There's no room for more columns to describe it. > >> > >> I suggest we abandon the table-version, as I don't know how it can be > >> changed to work out. > > > > > > Hm... How about keeping both? > > Well, I'll abandon the single table versions that are just unmanageable, and > focus on the bullet style, and multiple tables versions. > > I'll keep fiddling. Maybe something turns out OK after shaking the tree long > enough. > > > Daniel K. > > ___ > dmarc mailing list -- dmarc@ietf.org > To unsubscribe send an email to dmarc-le...@ietf.org ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/29/24 19:06, Alessandro Vesely wrote: > On Sun 29/Dec/2024 01:13:59 +0100 Daniel K. wrote: >> I opted to remove the words [...] > > There are still several "must contain", though. In particular, mind "A > single > report MUST contain data for one policy configuration.", which has changed. This is inherited from the old version. I tried hard to preserve all the information, rearrange the previous prose into something new, and expanding it to be complete. I intend to do incremental changes as separate commits, so that it stands out properly and eases reviewing. Do not pay too much attention to all the details, as I'm primarily exploring the layout at this point. In particular, the text of the bullet style version may not be exactly the same as the text in the table versions. > Perhaps somewhere we should say that "count" is the only non-key field. I'll collect it for later. >> 3.1.1.2. Multiple tables version > > This is the one I like better. It allows each table to be furnished with > comments common to various fields, e.g. the begin and end ind date_range. What I dislike about this alternative is the variable width of the different tables. Maybe there's some magic that can be applied to the syntax that avoids it, or maybe it doesn't stand out so much if it is rearranged as you suggest below. > Possibly, each table could be moved to the specific section; for example, > (the > remaining part of) Handling Domains in Reports could stay together with the > identifier table. I don't think I want to spread it around too much, but I'll try it out. >> 3.1.1.3. Single table version >> 3.1.1.4. Single table version 2 > > OTOH, the REQUIRED/ OPTIONAL column is better recognizable. We could give > up > capital case in the table versions, and replace those values with yes/no. I'll try to put just an 'R' by the required elements. Should be shorter, at least, but also more visible, as the optional elements will not have a marker. >> At the end of 3.1.1.3, there's a few paragraphs that did not quite fit >> in a particular place in the table. I don't think it fits perfectly at >> the end either. > > > They may make better sense in the multiple tables version. Indeed, they are already close to the relevant tables there. >> The tables also lose information on where the order of elements is >> mandated by the XSD. There's no room for more columns to describe it. >> >> I suggest we abandon the table-version, as I don't know how it can be >> changed to work out. > > > Hm... How about keeping both? Well, I'll abandon the single table versions that are just unmanageable, and focus on the bullet style, and multiple tables versions. I'll keep fiddling. Maybe something turns out OK after shaking the tree long enough. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Sun 29/Dec/2024 01:13:59 +0100 Daniel K. wrote: On 12/16/24 09:51, Alessandro Vesely wrote: That's notable and neatly structured. Perhaps /Must contain/'s can be slashes. Thank you for your input. I think you meant that it could be wrapped in underscores to be rendered as italicized, but that only works in the HTML version, and looks messy in the plain text version. I opted to remove the words, but feel free to explain better what you meant if I misunderstood and you want me to try something in particular. Removing was exactly what I meant. Sorry for the confusion. There are still several "must contain", though. In particular, mind "A single report MUST contain data for one policy configuration.", which has changed. Would a table help to further reduce the "A begat B; B begat C" effect? Consider https://en.wikipedia.org/wiki/DMARC#Aggregate_reports I may not fully have caught on here, and how to fix it. The nature of describing XML in element order necessitates a bit of repetition. I've experimented quite a bit the previous weeks, and I've prepared a new render with a few variations. https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-variants.txt There's also an HTML version - change the extension if you want to see it. Curiously, the list version looks nicer in txt than html. The table version is not the kind of table I meant, but I like it. Perhaps somewhere we should say that "count" is the only non-key field. 3.1.1.1. Prose version - must contain removed Basically the same as before, but with the 'Must contain' introduction removed. That wording certainly got a bit repetitive. 3.1.1.2. Multiple tables version This is the one I like better. It allows each table to be furnished with comments common to various fields, e.g. the begin and end ind date_range. Possibly, each table could be moved to the specific section; for example, (the remaining part of) Handling Domains in Reports could stay together with the identifier table. 3.1.1.3. Single table version 3.1.1.4. Single table version 2 The single table versions differ in how they communicate the level or depth of the element in the XML hierarchy. As you can see, I've tried a few things, but I think all of the table variants suffer from the restrictions of tables when it comes to formatting the details or nuances we describe for a particular element. Especially 'record' and 'reason' seem to suffer. OTOH, the REQUIRED/ OPTIONAL column is better recognizable. We could give up capital case in the table versions, and replace those values with yes/no. At the end of 3.1.1.3, there's a few paragraphs that did not quite fit in a particular place in the table. I don't think it fits perfectly at the end either. They may make better sense in the multiple tables version. The tables also lose information on where the order of elements is mandated by the XSD. There's no room for more columns to describe it. I suggest we abandon the table-version, as I don't know how it can be changed to work out. Hm... How about keeping both? Best Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/16/24 09:51, Alessandro Vesely wrote: > That's notable and neatly structured. Perhaps /Must contain/'s can be > slashes. Thank you for your input. I think you meant that it could be wrapped in underscores to be rendered as italicized, but that only works in the HTML version, and looks messy in the plain text version. I opted to remove the words, but feel free to explain better what you meant if I misunderstood and you want me to try something in particular. > Would a table help to further reduce the "A begat B; B begat C" effect? > Consider https://en.wikipedia.org/wiki/DMARC#Aggregate_reports I may not fully have caught on here, and how to fix it. The nature of describing XML in element order necessitates a bit of repetition. I've experimented quite a bit the previous weeks, and I've prepared a new render with a few variations. https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting-variants.txt There's also an HTML version - change the extension if you want to see it. 3.1.1.1. Prose version - must contain removed Basically the same as before, but with the 'Must contain' introduction removed. That wording certainly got a bit repetitive. 3.1.1.2. Multiple tables version 3.1.1.3. Single table version 3.1.1.4. Single table version 2 The single table versions differ in how they communicate the level or depth of the element in the XML hierarchy. As you can see, I've tried a few things, but I think all of the table variants suffer from the restrictions of tables when it comes to formatting the details or nuances we describe for a particular element. Especially 'record' and 'reason' seem to suffer. At the end of 3.1.1.3, there's a few paragraphs that did not quite fit in a particular place in the table. I don't think it fits perfectly at the end either. The tables also lose information on where the order of elements is mandated by the XSD. There's no room for more columns to describe it. I suggest we abandon the table-version, as I don't know how it can be changed to work out. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On Sun 15/Dec/2024 21:51:16 +0100 Daniel K. wrote: On 12/12/24 18:23, Daniel K. wrote: I believe I've included every bit of knowledge from the old text. It is currently formatted for ease of editing, for me, so please do not pay too much attention to all the seemingly extra empty lines. This version also adds the "generator" element that's been discussed. I've rendered a version based on an updated version, see: https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting.txt or, if you prefer: https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting.html Read from the end of section 2.1, after the last bullet list. That's notable and neatly structured. Perhaps /Must contain/'s can be slashes. Would a table help to further reduce the "A begat B; B begat C" effect? Consider https://en.wikipedia.org/wiki/DMARC#Aggregate_reports Best Ale -- ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/12/24 18:23, Daniel K. wrote: > I believe I've included every bit of knowledge from the old text. It is > currently formatted for ease of editing, for me, so please do not pay > too much attention to all the seemingly extra empty lines. This version > also adds the "generator" element that's been discussed. I've rendered a version based on an updated version, see: https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting.txt or, if you prefer: https://ietf.vendo.no/draft-ietf-dmarc-aggregate-reporting.html Read from the end of section 2.1, after the last bullet list. The source is here: https://github.com/d-javu/draft-ietf-dmarc-aggregate-reporting/commit/a05696381acd90c735b3e1e21db77dd95d7de3dd > I'm planning to: > > * Incorporate/move comments from the XSD to here. I have a bit left here, but it's mostly in shape. > * Explore the format used in the dmarcbis, Abandoned, I opted for a list/bullet style as explained in the second paragraph of 2.1.1. > * Double check all references for copy/paste mistakes. > > * Make a final version that actually renders well. More eyes needed, I'll polish this if the general direction this is going is deemed OK. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/3/24 20:46, Daniel K. wrote: > On 12/2/24 16:03, Brotman, Alex wrote: >> I'm not opposed to changing to this style/format, but I think we need >> consensus from the group that they prefer one style or the other. > > I take this as slight encouragement. Just wanted to know that it was not > totally off the mark. > > I'll continue working on it. Here's a link to what's currently in my wip branch. https://github.com/ietf-wg-dmarc/draft-ietf-dmarc-aggregate-reporting/commit/e596256387d87953a63a0dc8a1c071c80611c041 Apologies for not posting the text here, but it would be quite a job to format it intelligibly. I believe I've included every bit of knowledge from the old text. It is currently formatted for ease of editing, for me, so please do not pay too much attention to all the seemingly extra empty lines. This version also adds the "generator" element that's been discussed. I'm planning to: * Incorporate/move comments from the XSD to here. * Explore the format used in the dmarcbis, keyword: : Definition to see how that looks. This version has not even been rendered. If you try you get to keep both pieces. * Double check all references for copy/paste mistakes. * Make a final version that actually renders well. Please, do not hesitate to make it known if there are any glaring mistakes here. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
Am 2024-12-02 um 17:03 schrieb Brotman, Alex: Apologies on the late response, holiday travel. I'm not opposed to changing to this style/format, but I think we need consensus from the group that they prefer one style or the other. I prefer Daniel's bullet-point style, if we have the time to flesh out, review and polish it. Regards, Matt ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
On 12/2/24 16:03, Brotman, Alex wrote: > Apologies on the late response, holiday travel. No worries, I know it was turkey weekend on that side of the pond. :) > I'm not opposed to changing to this style/format, but I think we need > consensus from the group that they prefer one style or the other. I take this as slight encouragement. Just wanted to know that it was not totally off the mark. I'll continue working on it. Daniel K. ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
[dmarc-ietf] Re: Proposal for new prose describing the aggregate report XML
Apologies on the late response, holiday travel. I'm not opposed to changing to this style/format, but I think we need consensus from the group that they prefer one style or the other. -- Alex Brotman Sr. Engineer, Anti-Abuse & Messaging Policy Comcast > -Original Message- > From: Daniel K. > Sent: Friday, November 29, 2024 10:29 AM > To: dmarc@ietf.org > Subject: [dmarc-ietf] Proposal for new prose describing the aggregate report > XML > > Artart review pointed out that the description of the XML format was next to > unreadable, and expressed his concern that it was only really defined in THE > XSD > in Appendix A. > > Here is the start of something I would like to get your feedback on before > writing > it all up. > > I was thinking this would replace everything in 2.1 after the longer list of > bullet > points. > > I've not decided about using the list of tags in the lines starting > "REQUIRED/OPTIONAL elements are ...", adding the REQUIRED-ness after the > "element" bullet, or a combination. I included it all to show both options. > > Please let me know if this is on the right track, completely bonkers, or > something > in between. I'll be grateful for any other input you may have. > > > ### Description of the content XML file > > The format for these reports is also defined in an XML Schema Definition > (XSD) in Appendix A. > > DMARC Aggregate Reports have the root element "feedback" with its XML > namespace set to the DMARC namespace. It contains up to 5 different types of > elements, in order: "version", "report_metadata", "policy_published", > "extension" > and "record". > > * "version": OPTIONAL; MUST have the value 1.0. > > * "report_metadata": REQUIRED; > > REQUIRED elements are "org_name", "email", "report_id", > and "date_range". > OPTIONAL elements are "extra_contact_info", "error", > and "generator". > > * "org_name": REQUIRED; > The name of the Reporting Organization > > * "email": REQUIRED; > Contact to be used when contacting the Reporting Organization > > * "extra_contact_info": OPTIONAL; > Additional contact details > > * "report_id": REQUIRED; > Unique Report-ID, see 2.5.1 > > * "date_range": REQUIRED > MUST contain the elements "begin" and "end" > as epoch timestamps. > > * "error": OPTIONAL; > Error messages when processing DMARC Policy Record > > * "generator": OPTIONAL; > The name of the software involved, helps the Report > Consumer in where to report bugs. > > * "policy_published": REQUIRED; > > Records the DMARC Policy Record configuration observed by the receiving > system. > >REQUIRED elements are "domain", "p", "sp". >OPTIONAL elements are "fo", "adkim", "aspf", "testing", >and "discovery_method". > >* "p" The value from the discovered "p" tag. > >[Needs fleshing out] > > * "extension": OPTIONAL; > > Provides for future extensibility. > > * "record": REQUIRED; > > A report MAY contain an unlimited number of "record" elements, at least one is > REQUIRED. > > [Needs fleshing out] > > > Daniel K. > > ___ > dmarc mailing list -- dmarc@ietf.org > To unsubscribe send an email to dmarc-le...@ietf.org ___ dmarc mailing list -- dmarc@ietf.org To unsubscribe send an email to dmarc-le...@ietf.org
