Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-structure profiles sections - closes #214 and closes #248 #260

Merged
merged 1 commit into from
Aug 31, 2022

Conversation

benfrancis
Copy link
Member

@benfrancis benfrancis commented Aug 10, 2022

This is a proposed re-structuring of the profiles sections, based on the discussion in #214.

Overview of changes:

  1. Renamed "HTTP Profile" to "Common Constraints"
  2. Moved Default Language, Links and Security Schemes sections to the top level of this section
  3. Moved Information Model, Discovery and Errors sections from HTTP Baseline Profile to Common Constraints
  4. Merged the Security section from HTTP Baseline Profile into the Security section of Common Constraints and removed the placeholder Transport Security section in favour of the note referring to the Security Best Practices document
  5. Added a placeholder section for Semantic Annotations in Common Constraints
  6. Moved Privacy Considerations and Security Considerations into their own top level sections at the end of the document
  7. Added assertions to the three profiles to say that they require the constraints in the Common Constraints section to be conformed with
  8. Renamed a bunch of HTML element IDs to reflect the new structure
  9. Re-worded some assertions to reflect renamed section titles

After these changes, at a high level the specification looks like:

  • Common Constraints
    • Information Model
    • Security
    • Discovery
    • Links
    • Errors
    • Semantic Annotations
    • Default Language
  • HTTP Baseline Profile
    • Identifier
    • Protocol Binding
  • HTTP SSE Profile
    • Identifier
    • Protocol Binding
  • HTTP Webhook Profile
    • Introduction
    • Identifier
    • Message Format
    • Protocol Binding
  • Privacy Considerations
  • Security Considerations

If we land these changes then we'll also need to update the Introduction and Abstract to reflect renamed sections. I didn't do that in this PR because it's already large enough!

I also think we should consider renaming "HTTP Baseline Profile" to "HTTP Basic Profile", since the name "Baseline Profile" may now be confused with "Common Constraints".

My comments in #214 (comment) regarding the Information Model and Message Format sections are left unresolved for now.

Note: This diff is hard to read because it touches so many lines, but it's slightly easier if you just view the second commit (the first one is pulled in from #249 and may be re-based out if that lands first).

Edit: I've renamed HTTP Profile Common Constraints to Common Constraints for simplicity, since all the profiles are currently HTTP profiles. We can re-visit if other profiles are added in the future.


Preview | Diff

Copy link
Contributor

@mlagally mlagally left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @benfrancis for this contribution.
It significantly improves the structure.

@mlagally
Copy link
Contributor

@benfrancis , can you please resolve the merge conflict.

@benfrancis
Copy link
Member Author

@benfrancis , can you please resolve the merge conflict.

Done.

@mlagally
Copy link
Contributor

Approved in Profile call on Aug 31.

@mlagally mlagally merged commit fb3bfe4 into w3c:main Aug 31, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants