Initial draft of XACML 4.0 in markdown is available

[steven-legg]

I've pushed an update to xacml-v4.0-csd01.md on the xacml-4.0-core-spec branch that contains most of the text from XACML 3.0 plus errata.

I also edited the content to remove policy sets and their related definitions. The rule and policy combining algorithms have just become combining algorithms. The legacy combining algorithms are removed.

I didn't copy the examples yet because they will be extensively changed before we get to a final draft.

The images in section 3 are verbatim from the XACML 3.0 spec but will need some revision. I don't suppose anyone has the original source?

I left gaps in the section numbering where sections were deleted. There's a lot more reorganization to come so we can leave a tidy up to later, since we seem to have to manage the numbering manually.

I couldn't find a way to make an indented paragraph so I used bullet points instead. The style sheets seem to be creating indented paragraphs for the OASIS boilerplate though.

GitHub makes a reasonable effort to format the markdown but the result is not the same as processing it through pandoc. You could install pandoc and process the markdown yourself but to save you the trouble here is a zip file with the output: xacml-spec-distribution.zip It would be nice to automate this publishing step somehow.

The code snippets use a font size that I think is too small (in the pandoc output).

I fixed typos, wonky use of keywords and misdirected links as I found them.

[cdanger]

Thanks for the great work @steven-legg 👍 A few comments:

1. I noticed the ToC is generated at the top and not in the ToC section
2. This is probably a good opportunity to replace the PNG of figures 1, 2 and 3 with higher-quality SVG diagrams, ideally generated by pandoc directly from text descriptions inside the markdown (using for example Mermaid, Plantuml, GraphViz...):

• Figure 1 (data-flow digram) this is my attempt with GraphViz - the diagram can then be generated by Pandoc from the GraphViz source using a Lua filter. Ideally, my goal is to have pandoc generate the SVG (highest quality) from it for the HTML output. But I still have to test that filter to make sure it works as expected. I also tried with Plantuml and Mermaid (instead of GraphViz) but it was a failure :-(. Maybe if we change this data-flow diagram to a standard UML sequence diagram, that would be more feasible with those two, but that's something to be discussed. Only issue with GraphViz is that I couldn't get straight lines for steps 5 and 11 :-( so it looks less natural than the original. If you think that's too bad, then another alternative would be to redo the diagram with some more advanced free open source tool like Draw.io (rather than Visio), but then the SVG has to be generated separately, not directly with Pandoc as far as I know.

• Figure 2 and figure 3 (which is standard class diagram) should be feasible with Mermaid. Have to try. A nice feature of Mermaid is that it is natively supported (diagram is generated automatically) by Github when included in the Markdown.

[steven-legg]

1. I noticed the ToC is generated at the top and not in the ToC section

This is intended by TC Admin. From the original starter file commenting on pandoc:
"Note this command generates a Table of Contents (TOC) in HTML which is located at the top of the HTML document, and which requires additional editing in order to be published in the expected OASIS style. This editing will be handled by OASIS staff during publication."

[cdanger]

Understood 👍

[humantypo]

Yes, your GraphViz data-flow diagram looks 100% better than what I came up with using mermaid:

https://parducci.net/xfr/data-flow.html 🤢

Perhaps there are ways to adjust the formatting, but in my experience it's best suited for simple flows.

Personally, I'd rather have the precision and flexibility of something like Omnigraffle generate the SVG, but whatever works...

[cdanger]

Yes, your GraphViz data-flow diagram looks 100% better than what I came up with using mermaid:

https://parducci.net/xfr/data-flow.html 🤢

Wow 😲 I didn't get that far ! I appreciate the effort 😉 .

[cdanger]

Generating figure 2 with Mermaid:

block-beta  
    columns 7
    block:left
        columns 1
        space
        space
        in["domain-specific<br>inputs"]
    end
    
    block:shadedarea:5
        columns 5
        space:2 policy("xacml<br>Policy.xml") space:2
        space:5
        request("xacml Context/<br>Request.xml") space pdp("PDP") space response("xacml Context/<br>Response.xml")       
        policy --> pdp
        request --> pdp 
        pdp --> response
    end
    block:right
        columns 1
        space
        space
        out["domain-specific<br>outputs"]
    end    
    in --> request
    response --> out
    %% styles
    classDef default stroke:black,rx:5px,ry:5px
    style left opacity:0
    style right opacity:0  
    style shadedarea fill:lightgray
    classDef whitebox fill:white
    class policy,pdp,request,response,in,out whitebox
    

Loading

Same thing but with big/thick arrows:

block-beta  
    columns 9
    block:left:2
        columns 2
        space:2
        space:2
        input["domain-specific<br>inputs"] 
        input_arrow<["&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"]>(right)
    end
    
    block:shadedarea:5
        columns 5
        space:2 policy("xacml<br>Policy.xml") space:2
        space:2 down_arrow<["&nbsp;&nbsp;&nbsp;"]>(down) space:2
        request("xacml Context/<br>Request.xml") pdp_input_arrow<["&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"]>(right) pdp("PDP") pdp_output_arrow<["&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"]>(right) response("xacml Context/<br>Response.xml")       
    end
    block:right:2
        columns 2
        space:2
        space:2
        output_arrow<["&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"]>(right) output["domain-specific<br>outputs"]
    end    

    %% styles
    classDef default stroke:black,rx:5px,ry:5px
    style left opacity:0
    style right opacity:0  
    style shadedarea fill:lightgray
    classDef whitebox fill:white
    class policy,pdp,request,response,input,output,input_arrow,output_arrow,pdp_input_arrow,pdp_output_arrow,down_arrow whitebox

Loading

[cdanger]

Generating figure 3 (based on #11 new model) with Mermaid looks messy 😞 (I can't do straight links or avoid overlapping) :

%%{init: {'theme':'neutral'}}%%
classDiagram
%% Issue: no sharp curves or straight lines. See https://github.com/mermaid-js/mermaid/issues/2067 and https://github.com/mermaid-js/mermaid/issues/2817
%% Issue: overlapping edges
    %% Policy "0..1"*--"1" Description
    %% Policy "0..1"*--"1" PolicyIssuer
    %% Policy "0..1"*--"1" PolicyDefaults
    %% Policy "*"*--"1" Parameter
    Policy "1"*--"1" CombiningAlgorithm
    Policy "*"*--"*" Policy
    Policy "0..1"--"1" Condition

    Policy "*"*--"1" Rule
    %% Policy "*"*--"1" CombinerParameter
    %% Policy "*"*--"1" VariableDefinition
    Policy "*"*--"1" NoticeExpression
    %% Policy "1"*--"1" PolicyId
    %% Policy "1"*--"1" Version

    %% Policy "1"*--"1" MaxDelegationDepth

    %% Rule "0..1"*--"1" Description
    Rule "0..1"*--"1" Condition
    Rule "*"*-- NoticeExpression
    %% Rule "1"*--"1" RuleId 
    Rule "1"*--"1" Effect 

Loading

I shall try with PlantUML.

[cdanger]

Generating figure 3 with PlantUML looks much better 😄 :

@startuml
hide circle
'skinparam linetype ortho

' Policy "0..1" *-- "1" Description
' Policy "0..1" *-- "1" PolicyIssuer
' Policy "0..1" *-- "1" PolicyDefaults
' Policy "*" *-- "1" Parameter

Policy "*" *-- "*" Policy
Policy "1" *-left- "1" CombiningAlgorithm: \t
Policy "0..1" *-- "1" Condition
Policy "*" *-- "1" Rule
' Policy "*" *-- "1" CombinerParameter
' Policy "*" *-- "1" VariableDefinition
Policy "*" *-- "1" NoticeExpression
' Policy "1" *-- "1" PolicyId
' Policy "1" *-- "1" Version
' Policy "1" *-- "1" MaxDelegationDepth

' Rule "0..1" *-- "1" Description
Rule "0..1" *-left- "1" Condition: \t
Rule "*" *-right- "1" NoticeExpression: \t
' Rule "1"*--"1" RuleId 
Rule "1" *-- "1" Effect 
@enduml

[cdanger]

I couldn't find a way to make an indented paragraph so I used bullet points instead. The style sheets seem to be creating indented paragraphs for the OASIS boilerplate though.

I found a way to do it with pandoc extension "definition_lists". All there is to do is to replace the * the_definition with : the_definition in the markdown, and gfm with gfm+definition_lists in the pandoc command. I tested this on my personal repo for the Glossary section, please check it here and let me know if it's fine and I'll apply the change to our xacml 4.0 branch. As you'll see, it looks the same as before except no more bullets.

GitHub makes a reasonable effort to format the markdown but the result is not the same as processing it through pandoc. You could install pandoc and process the markdown yourself but to save you the trouble here is a zip file with the output: xacml-spec-distribution.zip It would be nice to automate this publishing step somehow.

I fixed typos, wonky use of keywords and misdirected links as I found them.

I also fixed formatting issues with several XML tags, quotes and such, also added syntax highlighting for XML blocks and pseudo-codes (combining algorithms).

[humantypo]

The formatting looks good on my phone. bOn Sep 26, 2024, at 9:29 AM, Cyril Dangerville ***@***.***> wrote: I couldn't find a way to make an indented paragraph so I used bullet points instead. The style sheets seem to be creating indented paragraphs for the OASIS boilerplate though. I found a way to do it with pandoc extension "definition_lists". All there is to do is to replace the * the_definition with : the_definition in the markdown, and gfm with gfm+definition_lists in the pandoc command. I tested this on my personal repo for the Glossary section, please check it here and let me know if it's fine and I'll apply the change here. As you'll see, it looks the same as before except no more bullets. GitHub makes a reasonable effort to format the markdown but the result is not the same as processing it through pandoc. You could install pandoc and process the markdown yourself but to save you the trouble here is a zip file with the output: xacml-spec-distribution.zip It would be nice to automate this publishing step somehow. I fixed typos, wonky use of keywords and misdirected links as I found them. I also fixed formatting issues with several XML tags, quotes and such, also added syntax highlighting for XML blocks and pseudo-codes (combining algorithms). —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>

[cdanger]

Following a suggestion of @steven-legg in previous meetings IIRC, I'd like to create a Github workflow/action here to generate the HTML output automatically (with the pandoc command) and publish to the github pages. (I guess the URL would be something like https://oasis-tcs.github.io/xacml-spec/xacml-v4.0-csd01.html but the last part can be changed.) This way, one can see the latest draft in HTML without installing pandoc or downloading/checking out the repo with git, whenever one of us makes changes to the markdown. I tested a working github action for this on my personal repo already, that's how I got the link mentioned earlier.

However, in order to do that, one of you with admin permissions (I don't have) need to change the Settings on this repository in order to allow publishing Github pages from the xacml 4.0 branch: go to Settings > Environments, create a new environment called github-pages if not already there, or click on it to configure it; go to Deployment branches and tags, Set to Selected branches and tags and add the xacml-4.0-core-spec branch to the list.

@humantypo @Hal-Lockhart (or @steven-legg if you have admin permissions) could you do that change please? Or if there is a different OASIS process to do such draft publishing, let me know.

[humantypo]

I will request from Oasis. (edited to remove artifacts from email reply—seems like there’s an issue with that)

[humantypo]

Oasis has followed the prescribed steps. Can you test?

[cdanger]

Which ones? I don't see a link.

[humantypo]

I have asked Oasis for clarification

[cdanger]

I have replaced the PNG pictures of the 3 figures in the markdown with Graphviz/Plantuml code, in order to generate SVGs in the HTML. You can check the result here for instance.

I also updated the pandoc command line in the markdown since it requires a few changes to use graphviz/plantuml tools.

[steven-legg]

Much better.

Figure 2 exceeds the page width. Can it be made smaller/narrower?

Can figure 3 be centered?

[cdanger]

Now the figure 2 is smaller (smaller arrows and smaller font size). And figure 3 is centered. HTML result:
https://oasis-tcs.github.io/xacml-spec/xacml-v4.0-csd01.html
(Make sure to hit Ctrl+R / F5 to refresh the page.)

[humantypo]

Does Graphviz/Plantuml have the ability to generate a “container” for the image (div)? I’m fine with whatever size they turn out but unless the image is bounded by something that can stylistically change in size dynamically I think it will be limited to certain rendering layouts.

[cdanger]

Not using graphviz/plantuml itself, but you can put markdown (e.g. a diagram) inside a <div> tag, and it is preserved in the HTML output from pandoc. This is how I centered the figure 3 as you can see in the markdown source, I wrapped the diagram in a <div style="text-align: center;">.

Also not sure whether this is what you were aiming for, but I've just customized the CSS so that the images are resized automatically when you shrink the HTML page:

[humantypo]

Yes. I think that solves the issue. The SVG should be nicely sized for the viewport that way. Nice job!

[steven-legg]

I couldn't find a way to make an indented paragraph so I used bullet points instead. The style sheets seem to be creating indented paragraphs for the OASIS boilerplate though.

I found a way to do it with pandoc extension "definition_lists". All there is to do is to replace the * the_definition with : the_definition in the markdown, and gfm with gfm+definition_lists in the pandoc command. I tested this on my personal repo for the Glossary section, please check it here and let me know if it's fine and I'll apply the change to our xacml 4.0 branch. As you'll see, it looks the same as before except no more bullets.

@cdanger Unless you are already doing it I propose to edit all the sections to use definition lists.

[cdanger]

I haven't done it for the other sections yet. You may do it, thanks (I'm a bit busy at the moment).

[steven-legg]

I've committed a change to convert the workaround bullet points into definition lists. The definition lists have some problems though. They don't work following a numbered paragraph or a code block.

[humantypo]

@steven-legg would you mind posting a specific example that we can play with?

[steven-legg]

In section 7.3.7 "AttributeSelector evaluation" in the latest xacml-v4.0-csd01.md there is a single underscore character following numbered paragraph 4. Take out that underscore and the immediately following indented paragraph will be rendered literally with a leading colon on the left margin. Adding spaces before or after the colon didn't change the behaviour.

The same thing will happen if any code block is followed by a line beginning with a colon.

I run pandoc directly on my laptop rather than using the Docker containers.

[cdanger]

OK I fixed it in section 7.3.7:
https://oasis-tcs.github.io/xacml-spec/xacml-v4.0-csd01.html#737-attributeselector-evaluation

Indeed, the indentation with the : text syntax does not work in list items, you have to use this pandoc syntax like on github markdown.

[steven-legg]

Bill and I have been doing some off-list experimentation on this. We can get the : text syntax to work following a list item or a code block by putting   on a line before it. However this causes a spurious extra blank line on Firefox and an odd character on Safari. Using <span> </span> (that's a space character in the middle) instead gets rid of the spurious blank line on Firefox, but the subsequent indented paragraphs still need to use  , which doesn't work for Safari. Pandoc translates the character entity into a literal non-breaking space character in the HTML. Perhaps Safari would work better if we could convince pandoc to output the character entity instead. Firefox and Chrome don't mind either way.

[cdanger]

Well, at least for the issue in list items, the fix I mentioned above works fine in Firefox/Chrome/Edge (I don't have Safari). For code blocks, I haven't tried, but I saw the issue only for the Note under the Data flow diagram. Is there any other section where this issue occurs ?

At least for the Notes, I re-formatted using '> text' (used for quotes usually) to make them look special / more visible. Let me know what you think (see the note below the figure here):
https://oasis-tcs.github.io/xacml-spec/xacml-v4.0-csd01.html#31-data-flow-model

[cdanger]

(Remember to refresh/reload the page to see the latest version.)

[steven-legg]

For code blocks, I haven't tried, but I saw the issue only for the Note under the Data flow diagram. Is there any other section where this issue occurs ?

It was an issue for translating version 3.0 Appendix A.3.12 "Higher-order bag functions" where bullet points have indented paragraphs intermixed with code snippets. For E.3.12 in the version 4.0 draft I reworked the text so that an indented paragraph didn't follow a code snippet. I can revert that to the arrangement in the old A.3.12 now that we have a way to reproduce the format.

At least for the Notes, I re-formatted using '> text' (used for quotes usually) to make them look special / more visible. Let me know what you think

It's sort of okay for notes but it would look out of place for A.3.12.

[humantypo]

I suggest we move forward with the "span" solution for this. If we have a proper html header in the doc, even Safari should be relatively happy.

[cdanger]

OK I am able to fix it for E.3.12 with a bulleted list like in the XACML 3.0 spec, but after checking the PDF output, I noticed there is no line break between the term and the definition in the definition lists, esp. in the Glossary, whereas it works perfectly fine in the HTML output. I'm surprised I missed that initially, or something has changed :-( . Trying to fix it... let me know if you get the same result on your side.

[humantypo]

I have found that Safari works much better if we add an explicit header to the md file.

<html lang="en">
<head>
    <meta charset="UTF-8">
    <link rel="stylesheet" href="https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3a.css">
</head>

[cdanger]

I fixed several issues with the PDF output ( commit d92f25b ), including the one mentioned previously regarding definition lists, and lines that were exceeding the page width, especially in code blocks. This requires a latex header file passed as pandoc -H argument to customize the PDF output, so the pandoc command line to use for PDF generation goes as follows (I added this to the Introduction section):

pandoc -f gfm+definition_lists -t pdf xacml-v4.0-csd01.md -c styles/markdown-styles-v1.7.3a.css -H custom_latex_header_for_pandoc_pdf_output.tex --toc --toc-depth=5 -s -L diagram.lua --metadata title="eXtensible Access Control Markup Language (XACML) Version 4.0" --embed-resources -o xacml-v4.0-csd01.pdf 

[steven-legg]

I committed the "span" solution for dealing with indented paragraphs following list items and code blocks.