Closed 4pins closed 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?
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.
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.
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."
Service Paths have been merged into the master branch.
The service path structure needs to be self documenting.