Work in Progress: Implementation Guide #501

ottonomy · 2022-12-16T18:52:51Z

Work in progress, do not merge. However, a PR provides a nice place to collect comments and discussion, where we can reference specific text.

TODO List:

Check all backtick-enclosed quoted terms for consistent application of the pattern. Use backticks (for <code> presentation of terms) for specific references to classes named in specifications. Do not use them for plain-english descriptions of the general concepts. e.g. Achievement is a class defined by the specs to represent the idea of an achievement. @xaviaracil
Check all spec references using [[OR-11]] spec references. Generally use a reference with a name link the first time the spec is referred to in a section/subsection, and use the proper name without further linking after. e.g. OneRoster [[OR-11]] is great. OneRoster lets institutions...
Check all links to OB and CLR specs to make sure they point to the final published location of these specs (rather than github.io pages preview locations, etc. It's important to be able to deep-link into these specs to specific headings, because they are long.
Apply consistent capitalization for headings. Currently roughly: H2 and Above Appear in Title Case and H3 and below appear in sentence case.
Apply desired consistent formatting for code snippets using <pre>
Add link(s) to reference implementations (1EdTech member-only)
Add links to conformance and certification suite at production location

ottonomy · 2022-12-29T21:15:24Z

I was having some trouble with the markdown formatter built into the Atom text editor that I was previously using, and on another project I found that Prettier did a fantastic job with markdown. In commit 1d87e92 I put a .prettierrc.json into the impl folder here just so that it would format on save in VS Code, but .editorconfig or .prettierrc stuff should probably be done at the repo level rather than just within this one folder. Once we're ready for merge of these markdown files, this local config file could be removed so that we can address the topic of code style and consistency as a separate effort.

jischr · 2023-01-05T17:22:59Z

ob_v3p0/impl/recommended-practices.md

+in the coming years as the consumer technology landscape and open source
+libraries develop.
+
+The OB 3.0 and CLR 2.0 specifications make no normative requirements strictly


this section is really nicely put after our recent discussions

jischr · 2023-01-05T17:24:23Z

ob_v3p0/impl/recommended-practices.md

+proceeds. Implementers are encouraged to join the 1EdTech community and discuss
+how we can further improve our implementations and guidance together.
+
+### Selecting recipient and issuer identifiers, such as DID methods


A similar section to this may be helpful for crypto algorithms?

I'm not a cryptography expert. I sketched out such a section in commit 0b3f6e3 that can start the conversation.

jischr · 2023-01-05T17:25:44Z

ob_v3p0/impl/conformance.md

+"Issuer", "Displayer", "Host" in one spot, and then Service Consumer (Read),
+Service Consumer (Write), Service Provider (Read), Service Provider (Write), and
+it hasn't yet incorporated the idea of "issuer only" certification that was
+referenced in recent meetings. Follow up and make consistent.


may be captured in the todo, but would be helpful to incorporate VC terminology such as Issuer and Holder into the below bullets.

jischr · 2023-01-05T17:27:06Z

ob_v3p0/impl/introduction.md

+-   Endorsement
+-   Re-issue a <= 3.0 Badge to a 3.0 Badge
+-   Authorization to Issue Given by Creator to Issuer
+-   Revocation of an Issued Credential


I'd recommend removing Revocation of an Issued Credential unless we are mentioning how revocation would work in the base spec.

I added a note about how the importance of the use cases and how revocation might be normatively covered in a future version of the spec in commit 232fba0. That's probably the optimal balance--I know some readers are really going to want to see something about revocation in here.

Historically it's been an important use-case and I tend to agree people new to this would find a mention of it helpful

Section 9.1 references a new revocation status solution:

If the credentialStatus property is present, and the type of the CredentialStatus object is "1EdTechRevocationList", determine if the OpenBadgeCredential has been revoked as shown in 1EdTech Revocation List Status Method.

ottonomy · 2023-01-12T00:16:36Z

ob_v3p0/impl/.prettierrc.json

+{
+    "trailingComma": "es5",
+    "semi": false,
+    "singleQuote": true,
+    "printWidth": 80,
+    "tabWidth": 4,
+    "proseWrap": "always"
+}


Note this .prettierrc.json will be removed before the final pull request. As a separate issue, a .editorconfig or similar may be added to the repository, consistently with 1EdTech architect recommendations for all next-generation 1EdTech specs.

...begin spaces vs tabs argument?

ottonomy · 2023-01-12T00:17:40Z

ob_v3p0/impl/help.md

@@ -0,0 +1 @@
+## Getting Help


Adding instructions here assigned to @xaviaracil

ahripak · 2023-01-12T14:37:02Z

ob_v3p0/impl/getting-started.md

+    format. See
+    [Dereferencing the Public Key](https://1edtech.github.io/openbadges-specification/ob_v3p0.html#dereference)
+-   When a client requests `Accept: */*` or `application/html`, an HTML
+    representation of the Achievement should be presented. This should express


Should this have a reference to conformance requirements?

I don't think it has ever been required or marked as "SHOULD" at the spec level to do this sort of content negotiation. Maybe a topic for the workgroup to consider, but I at least like this mentioned at the impl guide level.

ahripak · 2023-01-12T14:52:13Z

ob_v3p0/impl/introduction.md

+-   Endorsement
+-   Re-issue a <= 3.0 Badge to a 3.0 Badge
+-   Authorization to Issue Given by Creator to Issuer
+-   Revocation of an Issued Credential


Historically it's been an important use-case and I tend to agree people new to this would find a mention of it helpful

ahripak · 2023-01-12T14:57:37Z

ob_v3p0/impl/recommended-practices.md

+    resulting in a DID document. It relies on the DNS registration of a domain
+    holder, but many DIDs may be associated with any one domain or subdomain.
+
+Technically, this set of DID methods whose use is commonly observed among early


A fair warning/notice to future implementers!

ob_v3p0/impl/getting-started.md

Style and wording updates

ottonomy · 2023-03-08T00:00:05Z

Thanks to @xaviaracil for checking off most of those little formatting todos!

xaviaracil · 2023-04-18T17:00:50Z

Merging. Will track the addition of the reference implementation link in a separate issue

xaviaracil and others added 7 commits November 17, 2022 09:46

Initial outline

b7c1a7a

Add implementation guide introduction skeleton

e780d70

Stub out recommended practices for several challenges and use cases

c1b677d

IMPL: Add notes about DID methods to recommended practices

e8090cb

IMPL: Add references to use cases in each spec

e3ce9a0

IMPL Add note that CLR full document set should be linked

35365de

Use prettier for formatting of impl markdown files

1d87e92

jischr reviewed Jan 5, 2023

View reviewed changes

ottonomy added 2 commits January 9, 2023 17:06

Add note about revocation / status checking

232fba0

Add skeleton of crypto algorithm selection section

0b3f6e3

ottonomy marked this pull request as draft January 10, 2023 16:36

ottonomy added 3 commits January 10, 2023 18:12

Reference 1EdTech refresh and revocation companion specs

0685d79

Switch which alias is used to match the rest of the spec.

63eb80c

Add quickstart user stories and note about achievement IDs

efc2b61

ottonomy commented Jan 12, 2023

View reviewed changes

ob_v3p0/impl/help.md

@@ -0,0 +1 @@

## Getting Help

Copy link

Contributor Author

ottonomy Jan 12, 2023

Choose a reason for hiding this comment

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

Adding instructions here assigned to @xaviaracil

ottonomy and others added 2 commits January 11, 2023 16:21

Finish incomplete paragraph about issuer identifiers.

bfda823

Some words about getting help

4284426

ahripak reviewed Jan 12, 2023

View reviewed changes

ottonomy and others added 4 commits January 12, 2023 09:20

Update spelling, formatting of getting help.

dc972fc

written down some words

5871b44

Update section on conformance certification

050d3b9

Clarify identifiers for issuer

4a6b141

jischr reviewed Jan 26, 2023

View reviewed changes

ob_v3p0/impl/getting-started.md Outdated Show resolved Hide resolved

ottonomy and others added 5 commits February 9, 2023 08:52

Correct mistaken did:web identifier

effd223

Remove todo

24189c6

apply consistent formatting to reference-impls

3785012

Added some references

49fe1f9

Written down some words in OB/CLR in the 1EdTech Ecosystem

915db78

ottonomy and others added 11 commits February 22, 2023 12:00

Adjust language

70326f3

Add note about OB 2.0 and 3.0 simul-implementation

2ff26c2

update contributor affiliation

77e0508

Add recommendation for CLR 2.0 upgrade path

aa3de00

Added entry for CLR 2.0 cert suite

973f219

Fixed some bibliographic references

fa69304

Added entry for DID Web Method Specification

9c494c3

Fixed biblographic references

5c86748

Fixed bibliographic references

4250d9a

Style and wording updates. WIP.

8bd9579

Merge pull request #511 from 1EdTech/feature/impl-guide-editing

cb827a9

Style and wording updates

ottonomy marked this pull request as ready for review February 27, 2023 17:18

xaviaracil added 11 commits February 27, 2023 12:10

Defined 'we'

d96a879

Moved section upmost in the chapter

fd766ff

Added a note about token revocation

dfa00fa

Formatting changes

7386c9a

Added contributors of impl guide

8d8dff8

Fixed local contributors location

ebbc026

Links to spec points now to 1EdTech's site

0c068b8

Updated date

ef01a99

Applied consistent capitalization for headings.

059630d

Applied desired consistent formatting for code snippets using <pre>

dda2628

Updated to new version of context.json

7ff7794

xaviaracil added 4 commits March 30, 2023 17:00

Changed document status

d0242f2

Added link to certification suite

4ca3a97

Reference impl is written is java, not .net

f57c531

Merge branch 'develop' into feature/impl-guide

461d09d

xaviaracil merged commit e5c25da into develop Apr 18, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Work in Progress: Implementation Guide #501

Work in Progress: Implementation Guide #501

ottonomy commented Dec 16, 2022 •

edited by xaviaracil

Loading

ottonomy commented Dec 29, 2022

jischr Jan 5, 2023

jischr Jan 5, 2023

ottonomy Jan 10, 2023

jischr Jan 5, 2023

jischr Jan 5, 2023

ottonomy Jan 10, 2023

ahripak Jan 12, 2023

justinpitcher Jan 12, 2023

ottonomy Jan 12, 2023

justinpitcher Jan 12, 2023

ottonomy Jan 12, 2023

ahripak Jan 12, 2023

ottonomy Feb 9, 2023

ahripak Jan 12, 2023

ahripak Jan 12, 2023

ottonomy commented Mar 8, 2023

xaviaracil commented Apr 18, 2023

Work in Progress: Implementation Guide #501

Work in Progress: Implementation Guide #501

Conversation

ottonomy commented Dec 16, 2022 • edited by xaviaracil Loading

ottonomy commented Dec 29, 2022

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

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

Choose a reason for hiding this comment

ottonomy commented Mar 8, 2023

xaviaracil commented Apr 18, 2023

ottonomy commented Dec 16, 2022 •

edited by xaviaracil

Loading