search

Access4LearningNA / NADM

North American Data Model
2 stars 2 forks source link

Service Paths (Structure, Description, and Machine Readable) #8

Closed 4pins closed 9 years ago

4pins commented 9 years ago

The service path structure needs to be self documenting.

mattharris5 commented 9 years ago

You're describing these as needing to be "machine readable" but @jwrage described their benefit as being "human readable." Which is it?

jwrage commented 9 years ago

Qualifying... IMO the service path definitions are not rigorous enough to be beneficial outside of SIFA processes like certification and spec gen. I'm ambivalent about their inclusion in the XSDs, but they MUST be documented in non-normative ways. Ideally we could use a standard way to document them (RAML) but I also don't think it's worth holding up the release. Future iterations can improve on the basic idea of self documenting service paths within the XSDs.

mattharris5 commented 9 years ago

I'm not a big fan of their inclusion in the XSD's at all... and I know @NathanClinton is very opposed. But probably not the end of the world to include them if you think they need to be in there for xPress to work properly out of the gate. We can create a new issue for the 3.4 milestone to improve it.

4pins commented 9 years ago

The advantage of a service path is it is intuitive and convenient for a human programmer. The problem with this is a perception that they are self documenting. What does xRosters/{}/xStudents mean in both business terms and SIF schema terms? Rather than leaving everyone to figure it out on there own, we are trying to provide a human readable description and a machine readable query (more so all the programmers can see the relationships and implement them consistently as they may be used by an actual machine directly). Remember, "The schema is the standard."

4pins commented 9 years ago

Service Paths have been merged into the master branch.