Meeting minutes
<kaz> diff
<kaz> updated wd
Minutes
<kaz> May-24
Reviewing minutes from last meeting.
No objections to publishing minutes from last meeting.
Typo on independently.
Typo reachted -> reached
No objections to publishing minutes.
<kaz> (typos fixed)
FarshidT: Can we prioritise functional changes
McCool: Kaz has created a diff showing changes for publication, we will review this offline
<kaz> diff
McCool: Change log needs adding before we publish. Need a reviewer.
FarshidT: I can review.
McCool: Assuming review passes we can publish.
PR for TD signatures
<kaz> wot-thing-description PR 1151 - WIP: TD Signatures
McCool: Directories may need signatures. Need canonical form for signatures. May also need an expanded form.
Will discuss further on TD call. Have some feedback with some things to fix from security call, hopefully will have a more complete version by next week and can discuss discovery implications.
Discovery PRs
FarshidT: Created a PR with minor parts of refactor.
McCool: Ben has made updates to refactor PR
Also an alternative proposal from Ben
<kaz> wot-discovery PRs
(Reviewing a list of PRs)
Also one around pagination
Discussing
#180
<kaz> PR 180 - Create JSON Schema for validation of discovery extensions
McCool: I believe that in JSON schema have additional properties which describe things that are allowed. First want to validate against regular TD schema, and then against this. Is there a way to link to another schema?
FarshidT: First apply TD schema, then this one.
Cristiano: You can import, but maybe not the cleanest way. Programmatic approach (step 1, step 2) cleaner
McCool: Describe process in prose.
FarshidT: additionalProperties: true is already true so doesn't matter.
McCool: Maybe use dependencies, validate extensions.
Suggest merge it and move on, will add comments to PR.
No objections to merging.
PR 180
Resolution: Merge #180
PR 175
<kaz> PR 175 - Updated directory to new ontology model
Relates to Thing and EnrichedThing, not directory API itself
Andrea: This is just model, not the API
Now have Thing, ThinLink and ThingDirectory so they are consistent.
McCool: What order should we merge in?
FarshidT: Doesn't matter
Andrea: #175 is context, ontology and diagram
McCool: What generates this XML?
Andrea: A tool named chowlk
McCool: Good to check in diagrams as SVG files. Make sure SVG not just PNG so easier to edit.
Andrea: This is the source code of diagrams
McCool: If this tool is not available in the future, we want to be able to edit
Andrea: We can remove this file
McCool: If we want to edit in the future, can we start from TTL file?
Andrea: Yes
McCool: Will go ahead and merge this
FarshidT: We should squash it as there was back and forth
Cristiano: I see no cardinality in diagrams, is that intended?
FarshidT: I think there was, but in other PR
McCool: If there is cardinality in the ontology but not in the diagrams, that is inconsistent with diagrams in TD spec. Should make consistent with TD spec, please file an issue.
Resolution: Merge #175
PR #181
<kaz> PR 181 - Update exploration figures and types
FarshidT: It's a shame we can't see diagrams
There are two diagrams
McCool: I notice cardinality is here. Was the question before about this diagram?
Cristiano: There they are, it's fine.
McCool: I suggest merging, can always file issues and updates. Am a little concerned about the style because the style in the TD spec is different. Not a huge deal, but should use similar symbology.
FarshidT: There are also changes in the text describing diagrams.
McCool: Style differences can be aligned with TD spec. What tool were we using for diagrams in the main TD spec?
Cristiano: GraphViz?
FarshidT: I think GraphViz was used to generate visualisation
McCool: Updated types, names of things, thing link
Kaz: I checked, it was GraphViz
McCool: As long as both using UML standards should be OK, just don't want to use a different arrow type for subclass for example, need to check that.
FarshidT: New namespace URL we are using everywhere except here
McCool: When we go to CR we should update to official URIs
FarshidT: Internal references automatically extracts, extracts title
McCool: Some significant re-organisations to the text
McCool: Go ahead and merge this. Any objections?
McCool: Need more time to review?
Resolution: Will squash and merge #181
PR #186
<kaz> PR 186 - Move API spec to appendices
FarshidT: One more easy one. Moved the TD to the end in appendices. Still normative but moved it to appendices.
McCool: Technically you can't make appendices or examples normative.
McCool: What we should have is a Thing Model that is normative, assuming there is a TD for directories
McCool: If we move it, does it break other pending PRs?
FarshidT: For appendices there is a class to say whether they are normative
Have marked as a normative appendix
McCool: I was incorrect, didn't know you could do that. Fine with me.
Do need to convert it into a TM.
McCool: Could keep it as an example, then add a TM separately (without security stuff)
FarshidT: In the future we can add another section for OpenAPI
McCool: Security definitions are an example, not meant to be normative
Can remove non-normative parts and create a TM
FarshidT: These could be different subsections in appendices
McCool: Want to label interactions with scopes
McCool: No objections to merging, but future work to do
Kaz: Can move to appendices. At the moment proposed appendix is not normative?
McCool: It is normative, using a calss
*class
Kaz: It would be better to have section in main body if normative
FarshidT: The plan is to explain everything in normative text, then have the TD at the end
Kaz: For the moment moving to appendix while still normative fine but should add editor's note regarding moving to main body
McCool: Right now it's a TD anyway, which should be a TM. It's the TM we want to be normative. Put in appendix and cite it from the body is the right thing to do.
Kaz: Agree
McCool: Do we want to clutter body with assertions which are covered clearly in the TM?
McCool: It's a simple matter to move it up one level, still at the end but as a section.
Kaz: Why don't we just add an editor's note.
FarshidT: I can create an editor's note
McCool: Add editor's note saying we may need to make it into a section
McCool: Could just make it a section at the end
FarshidT: OK I will do that now.
McCool: Some conflicts need fixing too.
FarshidT: I can postpone the move until next stage.
PR #188
FarshidT: Ben had done a lot of work, but too many changes in one PR. Did not take part about separating events into different affordances.
<kaz> PR 188 - Refactor Directory Service API TD (stage 1)
FarshidT: Also separated out anonymous TD
McCool: Have added scopes. Need a rich set of scopes.
#188
Renamed URI template
Added a semantic annotation to say it's an ID
McCool: Need to explain that it's an ID that needs using later on
McCool: Is this a property or an action?
FarshidT: It is an action (partialUpdate)
McCool: Needs renaming?
FarshidT: partiallyUpdate?
benfrancis: Have removed all the substantial changes, and just renamed things?
Cristiano: We need to define this ThingID somewhere
McCool: Maybe we shouldn't call this ThingID, because it may be confused with the one in the TD spec
FarshidT: The one in the TD spec refers to an actual thing's ID, whereas here we just care about identifying a TD
FarshidT: It's actually not the same as the TD spec
McCool: Could call it ThingDescriptionID instead of ThingID. It's the ID of the thing description in the directory.
FarshidT: Should we call it retrieveTD then?
McCool: I'm worried about a name conflict with TD spec
FarshidT: The name is not identical
McCool: Even if different case, still confusing
McCool: Can merge and create an issue about this to discuss later
Cristiano: Agree
Cristiano: I can create issue
McCool: OK, so just name changes, bug fixes and "at type" for IDs
FarshidT: I have fixed the name to be a verb. Now partiallyUpdate
McCool: I would like to go ahead and merge this. Not ignoring other changes, just saying we can merge and move on. Ben can rebase his PR on this one.
McCool: Squash or separate
FarshidT: Better to keep separate so easier to rebase on top of
Resolution: Merge #188
McCool: Need to make a decision. Do we do remainder of refactor? Could just make the TD informative. Sounds like we could incrementally change, then make it informative. But hesitate to make it informative until we have all the text.
McCool: Could make it a normative appendix for now, make it an informative appendix later once normative text written.
#186
<kaz> PR 186 - Move API spec to appendices
McCool: There is a conflict, I can try to fix now
FarshidT: Can just remove section above.
FarshidT: Have removed editor's notes
(McCool edits PR to resolve conflicts and make fixes)
McCool: Shall we merge this now? Any objections?
Resolution: Merge #186
Refactor and Restructure
McCool: Need to discuss refactor/re-structure
McCool: I'm worried about the schedule, we are behind schedule. Going to talk to kaz and see how much slack we have. At most we have an extra month. Also worried about vacations, will be hard to make progress over the summer. Want CR draft by end of July at the latest.
McCool: Was recently thinking about TM being normative issue. If a TD has a link to a TM, is it really necessary to repeat everything in the TM, or indicate in the link that everything in the TM is re-used? If that was the case wouldn't need a big TD.
Someone needs to commit to writing a description of the API in prose.
<Ege> https://
Ege: In link relation types there is a type relation keyword
McCool: In a moment will look at Ben's PR and decide whether to merge remaining. The PR will probably not merge due to conflicts.
Also need to consider whether we want other protocols to be supported in the future and whether we depend too much on HTTP today.
Ege: Need to say which are core features which should be supported by all protocols
McCool: The idea of a TM is that in theory it is protocol independent
Ege: What are the core features?
McCool: Creating a TD, retrieving a TD, retrieving part of a TD etc.
McCool: The other thing Ege brought up is describing everything in prose. The prose section should use affordance names from the TM so we can relate it to the TM. Until we have the prose, can't do anything else.
FarshidT: Adding links to every part of the TM overkill, but can have a link
McCool: I think this is a cleanup step
McCool: We have a PR, it is probably now half a PR
McCool: I guess the original PR was only modifying the TD?
FarshidT: Yes that's correct
FarshidT: What is not merged is changing retrieval to actions
FarshidT: Also splitting events API into different affordances
McCool: Two different topics. Maybe we should discuss them one by one.
Which is easiest to resolve?
FarshidT: Actions
McCool: I agree that if it's a verb and it's a thing we're doing it should be an action
benfrancis: Turning into actions is not my idea, I thought it should be one property
McCool: (Looking at TD). A things property, actions to create, read, update and delete.
McCool: ID ends up being a URI variable.
partialUpdateThing would not work in non-HTTP protocols, correct?
Ege: Could do a partial update using other approaches, doesn't seem protocol dependent
Ege: In another protocol this would be done in a different way, because other protocols don't even have URIs
McCool: I see partial update as optional
No way to annotate that in TD, can do in TM
FarshidT: Actually an important feature
McCool: Not a blocking feature, I could replace the TD with a new one. Less efficient but still works.
FarshidT: Yes
McCool: Making it optional means we don't need to do it in other protocols.
McCool: Does anyone have any objections to this structure?
FarshidT: It's fine for me because the API is the same, but I don't understand why things is a property, and querying a single thing is an action. The actions are defined as safe and idempotent so far, but why is read all things not also an action?
FarshidT: My proposal is to make read all things an action as well
McCool: The things property represents the state of the directory
McCool: The affordances are listed separately to make it easier to use from Scripting API
FarshidT: I'm not suggesting to mix them, suggesting to move things property to be an action, to query everything and pagination
McCool: Things are the state of the directory, so it's logical that things is the collection of things
FarshidT: I disagree that things are the state of the directory, there are other things which are also state
McCool: The set of resources managed by the directory is its state
FarshidT: Would "subscribers" be another property of the directory
McCool: I can imagine doing that, if we wanted it
McCool: I'm not sure if that would make sense because we have events for that
FarshidT: It was just an example
McCool: We could have "models" later on
McCool: I'm personally OK with create, retrieve, update and delete as actions
Resolution: Agree to make create, update, delete, search operations actions. Farshid will create a PR with the subset of commits for this change.
things will be a property
Now discussing single vs. combined events
FarshidT: Two URI variables, type and full
Ben is proposing to change one thingRegistration event into thingCreated, thingUpdated, thingDeleted
McCool: In TDs we have events and have multiple classes of events
McCool: It seems to me we should have a way to subscribe to multiple events
FarshidT: There is no way to subscribe to all or multiple in the new proposal
FarshidT: Can't extend
McCool: Thing Directory could extend it. Could add additional event types.
McCool: Could add an extension in current version with changing enumerated types, not sure that's a good approach
FarshidT: Could extend
McCool: Put extension issue aside for now, different but possible
McCool: In current version, can subscribe to all events in a single step
FarshidT: In HTTP2 when there are multiple subscribers separately they will be combined, but requires TLS
McCool: We need a section about best practices and HTTPs
McCool: One of the best practices uses a proxy which provides TLS. Downside is that if internet goes down it doesn't work.
McCool: If do HTTP2 it would be taken care of
FarshidT: On the left there is no way to subscribe to multiple
McCool: We don't have to merge this, it's not going to be a blocker
McCool: Need to make a list of pros and cons and decide
McCool: Why don't we clean up the PRs and get the actions stuff cleaned up
McCool: If Ben can create a PR just for the event part and raise arguments for pros and cosn
benfrancis: (Explains rationale but didn't have time to write it down)
McCool: Agreeing with you, missing feature of TD spec
FarshidT: At this point I agree with splitting, only question is about names of events "create vs. created"
McCool: Any objections to making this change?
McCool: FarshidT will you create a PR to add this change?
FarshidT: Yes
Resolution: Separate events into three separate events
McCool: If we want a description of the API in prose, someone has to agree to write it
<kaz> [adjourned]