Why encapsulating the JSON array in an object?

[llemeurfr]

A narration JSON array is encapsulated in a JSON object with no property. IMHO this extra object is not needed for the representation of a narration and the array could be a top level element.

[marisademeglio]

I wanted consistency with the nested object case: https://github.com/w3c/sync-media-pub/blob/1557b464df1c7079c0ed71e76d51a66bf516a95c/docs/narration.html#L167

I suppose the top-level narration property could have a sibling role: "document" if we wanted to be (overly) thorough.

Also, narration is a nice clear term that describes exactly what the intention is.

But I also understand the argument for having fewer properties, and I do love deleting things.

[danielweck]

For what it's worth, this is a working JSON Schema for the current proposal:

sync-media-narration.schema.json:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://w3c.github.io/sync-media-pub/sync-media-narration.schema.json",
    "title": "JSON Schema for Narration Sync Media",
    "type": "object",
    "properties": {
        "role": {
            "description": "Type associated with this synchronized narration sequence, similar to EPUB3 'epub:type' attribute semantics, e.g. 'aside'",
            "type": [
                "string",
                "array"
            ],
            "items": {
                "type": "string"
            }
        },
        "narration": {
            "description": "Ordered list of children, similar to SMIL 'seq' element (recursive JSON Schema property)",
            "type": "array",
            "items": {
                "anyOf": [
                    {
                        "$ref": "sync-media-narration.schema.json"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "role": {
                                "description": "Type associated with this synchronized text/audio pair, similar to EPUB3 'epub:type' attribute semantics, e.g. 'footnote-ref'",
                                "type": [
                                    "string",
                                    "array"
                                ],
                                "items": {
                                    "type": "string"
                                }
                            },
                            "text": {
                                "description": "Document reference, similar to SMIL 'text' element, e.g. 'chapter1.html#paragraph1'",
                                "type": "string",
                                "format": "uri-reference"
                            },
                            "audio": {
                                "description": "Audio reference, similar to SMIL 'audio' element, e.g. 'chapter1.mp3?t=0,123'",
                                "type": "string",
                                "format": "uri-reference"
                            }
                        },
                        "required": [
                            "text",
                            "audio"
                        ]
                    }
                ]
            }
        }
    },
    "required": [
        "narration"
    ]
}

[danielweck]

... and here is a working example, validated against the above JSON Schema:

sync-media-narration.sample.json

{
    "narration": [
        {
            "text": "chapter1.html#id1",
            "audio": "chapter1.mp3#t=0.0,1.2"
        },
        {
            "text": "chapter1.html#id2",
            "audio": "chapter1.mp3#t=1.2,3.4"
        },
        {
            "role": "footnote-ref",
            "text": "chapter1.html#id3",
            "audio": "chapter1.mp3#t=3.4,5.6"
        },
        {
            "role": [
                "aside",
                "some-other-type"
            ],
            "narration": [
                {
                    "text": "chapter1.html#id4",
                    "audio": "chapter1.mp3#t=5.6,7.8"
                },
                {
                    "text": "chapter1.html#id5",
                    "audio": "chapter1.mp3#t=7.8,9.1"
                },
                {
                    "text": "chapter1.html#id6",
                    "audio": "chapter1.mp3#t=9.1,10.1"
                }
            ]
        },
        {
            "text": "chapter1.html#id7",
            "audio": "chapter1.mp3#t=10.1,11.2"
        },
        {
            "text": "chapter1.html#id8",
            "audio": "chapter1.mp3#t=11.2,13.3"
        },
        {
            "role": "footnote",
            "narration": [
                {
                    "text": "chapter1.html#id9",
                    "audio": "chapter1.mp3#t=13.3,14.4"
                },
                {
                    "text": "chapter1.html#id10",
                    "audio": "chapter1.mp3#t=14.4,17.4"
                }
            ]
        }
    ]
}

[danielweck]

You may try the above JSON Schema and JSON sample with these online tools:

https://jsonschemalint.com/#/version/draft-07/markup/json

https://www.jsonschemavalidator.net

[danielweck]

I added the JSON Schema and JSON sample to the source code repository: https://github.com/w3c/sync-media-pub/tree/master/schema

[llemeurfr]

I wanted to check the schema from the link but obtain an error message.

[danielweck]

All works fine at my end (just tested again). Can you please explain what error message you are getting?

[marisademeglio]

@danielweck @llemeurfr Can I close this issue or is there more to discuss?

[danielweck]

I am in favour of preserving the narration JSON property at the top level, as well as within nested structures, to explicitly denote the presence of a "sequence" timing container for synchronized text/audio pairs. On that basis, I would suggest closing the issue. However, this is Laurent's issue, so I will let him chime-in :)

[llemeurfr]

It was only a matter of simplification of the structure, at the cost of clarity. Let's keep the top-level narration then and close this issue then.