TM Forum Community

 View Only

  • 1.  A definition of 'machine readable'

    Posted Feb 02, 2021 03:01
    Edited by Paul Jordan Feb 02, 2021 05:51
    At Virtual Action Week @Ian Turkington asked what is the difference between machine readable and human readable specifications, given that in theory everything is machine readable.​
    I suggest that there are two tests for a spec to be machine readable:

    a) It must be expressed solely in text (we could debate the set of allowable encodings)
    b) It must conform to some defined syntax (we could debate the extent that this syntax must be formally defined and published in its own right). 

    Any other thoughts?

    #OpenDigitalArchitecture
    #General

    ------------------------------
    Paul Jordan
    BT Group plc
    ------------------------------


  • 2.  RE: A definition of 'machine readable'

    Posted Feb 02, 2021 03:20
    Hi Paul,

    Thanks for starting this discussion. In order to qualify my response I'd like to give a bit of context about why I separated human readable and machine readable in my presentation on how we organize ODA on Monday.

    As with any presentations I have had to find a few words to bring across a point, and often the words chosen do not reflect the full message. You will recall I was talking about the things we produce and I separated machine readable standards from human readable standards. The reason I separated these was broader than the specific question of what is machine readable.

    I observe in TM Forum we have load of deliverable which are documents which we publish. There are given document codes, they are reviewed and member approved and then published. This has been the bread-and-butter approach for TM Forum for many years, our processes and even our by-laws suit this approach very well. However more recently (i.e. a few years) we have increasingly produces deliverables which are code (swagger files, CTKs, etc.) And when you deliver code different frameworks are helpful. (E.g. github). The method or approval and release and versioning is also much more dynamic. For example we may support branching, minor versions, etc. All of these techniques are quite different to the approaches for documents.

    So If I can hijack your discussion thread, and consider if there are indeed two types of deliverable. And if so what are the key differences between the two, and how they should be handled. Once we are clear on the differences then we can revisit what they should be called (I think the machine readable / human readable terms I used may not work in the long term.)  

    Thanks,
    Ian Turkington, TM Forum


    ------------------------------
    Ian Turkington
    TM Forum
    ------------------------------



  • 3.  RE: A definition of 'machine readable'

    Posted Feb 02, 2021 05:08
    Interesting discussion. Perhaps what @Ian Turkington meant is to distinguish between​​ assets that are machine (or software) actionable as against assets that are consumed solely by humans. To take an obvious example from the world of Open APIs:
    • Swagger files and conformance test kits are machine actionable, in the sense that software is out there that can read and "understand" these assets (swagger by code-gen, CTK is installable/executable software). Humans are very likely to read the swagger (designers, developers), less likely to read the CTK.
    • User guide and conformance profile are not (to the best of my knowledge) machine actionable, in the sense that we don't have software out there (at the moment) that parses and takes action on these documents. (Note that these documents are actually partially generated by software, but that's not the point here).
    But I'm not sure that there is necessarily a distinction in the release process, why would you not have branching or minor versions also for non-machine-actionable assets.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------

    Original Message


  • 4.  RE: A definition of 'machine readable'

    Posted Feb 03, 2021 02:19
    Edited by Paavo Muranen Feb 03, 2021 02:19

    I like the idea by @Jonathan Goldberg about distinction based on 'actionability' and would like to refine it with measures of 'freetext contamination' where human intervention is needed when actions are needed. Flows which allow 'contamination' and still work are robust and when the contamination is detected in 'harmless' portions of the structured data, then automation is possible. This way even non-modular content is in better control. 

    e.g. footnote for a specific price in bid can prevent automation later on.

    rgrds Paavo Muranen

     



    ------------------------------
    Paavo Muranen
    Telia Company
    ------------------------------

    Original Message


  • 5.  RE: A definition of 'machine readable'

    Posted Feb 03, 2021 06:05
    Yes "actionable" is a better way to think about it.
    I also agree that documents and code should both be version managed, allow branches, etc. I guess the difference is often tooling and velocity. But you are correct we need to consider these concepts for all our deliverable.

    ------------------------------
    Ian Turkington
    TM Forum
    ------------------------------

    Original Message


  • 6.  RE: A definition of 'machine readable'

    Posted Feb 03, 2021 07:51
    Yes I also agree that 'machine readable' really infers machine actionable.

    Writing specifications in text makes it much easier to apply version management as mentioned by @Ian Turkington, which is my first suggested criteria.

    My second suggested criteria is that the specification must be conformant to a separately defined syntax. Examples of such syntax would be swagger, OAS3, YANG, TOSCA etc. Some of these allow for the inclusion of metadata which is explicitly defined as not actionable while several of them allow inclusion of comments which are also not actionable. Thus they do allow for escaping to '​​freetext contamination' as mentioned by @Paavo Muranen but such escaping should only be permitted where the referenced syntax allows it. A counter example would be where the syntax is JSON; JSON does not allow comments and I suggest that it would be be poor practice to define a JSON schema element which was designed to contain data which was intended to be a non-actionable escape.

    ------------------------------
    Paul Jordan
    BT Group plc
    ------------------------------

    Original Message


Related Content