vCard Annotation and Nested Annotations

[swhitley]

This is my recommendation for vCard in an annotation.

The properties are based on the hCard spec - http://microformats.org/wiki/hcard#Property_List

I am also introducing the idea of nested annotations by including geolocation within an annotations array.

I would like to discuss vCard and nested annotations in this thread.

{
    "type": "net.app.core.vcard",
    "value": {
        "fn": "Corky Crystal",
        "n": {
            "given-name": "Corky",
            "family-name": "Crystal"
        },
        "nickname": "Corks",
        "org": "Acme Inc.",
        "title": "Chief Chef",
        "adr": {
            "type": "Home",
            "street-address": "11 Lake Drive",
            "locality": "WonderCity",
            "postal-code": "5555",
            "region": "",
            "country-name": "Australia"
        },
        "tel": {
            "type":"Home",
            "value": "+61 7 555 5555"
        },
        "email": "corky@example.com",
        "annotations": [
            {
                "type": "net.app.core.geolocation",
                "value": {
                    "latitude": 74.0064,
                    "longitude": 40.7142
                }
            }
        ]
    }
}

annotations

[DaveWoodCom]

Nested annotations seem like an unnecessary complication. The normal vcard spec doesn't include an option for annotations so adding one just increases complexity without solving anything.

That said, if some annotation we add, calls for it's own annotations, then nested annotations should be used, but only in that case that calls for it, and I doubt they would be net.app.core.x annotations.

What is the benefit of putting the net.app.core.geolocation annotation inside the net.app.core.vcard annotation? It means you'd have to repeat it as a main annotation as well, or risk some clients not knowing where to look for that info.

Not only that, it would likely increase the load on the server when you do a query for all posts with a certain annotation if it has to parse all other annotations looking for nested ones...

I just don't see the point of this idea. If there is one, please explain...

Thanks.

[swhitley]

@DaveWoodCom I'm exploring what we'll do when we have composite schemas. We could just copy the net.app.core.geolocation properties (as I've done below). That's much simpler to generate and read.

I'm just wondering about apps that will consume this information when we start adding additional media; consider a document with multiple media attachments. Nested annotations would allow apps to use specialized annotation readers for each annotation type. Otherwise, the app will have to be aware of all of the different types that could be included within a particular schema.

I'm not saying this is the way to go, but I want to bring it up so that we can decide if we will copy, nest, or do something else entirely.

{
    "type": "net.app.core.vcard",
    "value": {
        "fn": "Corky Crystal",
        "n": {
            "given-name": "Corky",
            "family-name": "Crystal"
        },
        "nickname": "Corks",
        "org": "Acme Inc.",
        "title": "Chief Chef",
        "adr": {
            "type": "Home",
            "street-address": "11 Lake Drive",
            "locality": "WonderCity",
            "postal-code": "5555",
            "region": "",
            "country-name": "Australia"
        },
        "tel": {
            "type":"Home",
            "value": "+61 7 555 5555"
        },
        "email": "corky@example.com",
        "geo": 
            {
                    "latitude": 74.0064,
                    "longitude": 40.7142
            }
    }
}

[mattflaschen]

I agree with Dave. I would leave it out of vCard entirely, since it's not a vCard annotation. Then, just put two in the main array:

    "annotations": [
        {
            "type": "net.app.core.vcard",
            "value": {
                "fn": "Corky Crystal",
                "n": {
                    "given-name": "Corky",
                    "family-name": "Crystal"
                },
                "nickname": "Corks",
                "org": "Acme Inc.",
                "title": "Chief Chef",
                "adr": {
                    "type": "Home",
                    "street-address": "11 Lake Drive",
                    "locality": "WonderCity",
                    "postal-code": "5555",
                    "region": "",
                    "country-name": "Australia"
                },
                "Tel": {
                    "type": "Home",
                    "value": "+61 7 555 5555"
                },
                "email": "corky@example.com"
            }
        },
        {
            "type": "net.app.core.geolocation",
            "value": {
                "latitude": 74.0064,
                "longitude": 40.7142,
                "altitude": 4400,
                "horizontal_accuracy": 100,
                "vertical_accuracy": 100
            }
        }
    ]

That way parsing clients that understand only vCard, or only geolocation, get something without special effort, without needing to know both.

Also, why is only Tel capitalized?

[swhitley]

@mattflaschen Fixed the capitalization typo. :) The only issue I see with your example is that geo isn't necessarily associated with the vCard. There could be an image annotation with a different location in the same set.

[mattflaschen]

Doesn't a vCard represent a person overall? If so, there's no location associated with that. Of course, they have a home (and maybe work) address, but that's given explicitly and can be geocoded. Their location when posting might make more sense directly under the post anyway.

For photos, EXIF supports standard geolocation tags, so we may not need anything beyond that.

[swhitley]

@mattflaschen There's a geo component of vCard - http://microformats.org/wiki/hcard#Property_List

No one is jumping in to say we really need nested annotations, so I'm going to close that part of the discussion.

I'll focus on fleshing out the rest of vCard since I didn't include all of the properties in the first draft.

[swhitley]

I had one other thought on nesting. If we copy all of the properties, like I did in the last vCard example for geo, it might be helpful to provide an optional property called "namespace." It would be populated with the namespace that is being used for all of the elements in that part of the schema. Using a namespace property would instantly indentify the siblings and children. That would allow an app to use a special handler (in the example below, a geolocation handler), instead of handling the geo properties as part of the vCard handler.

Example:

...
      "geo": 
            {
                    "namespace": "net.app.core.geolocation",
                    "latitude": 74.0064,
                    "longitude": 40.7142
            }
...

[swhitley]

Full example for net.app.core.vcard proposal (based on http://microformats.org/wiki/hcard#Property_List and http://en.wikipedia.org/wiki/VCard):

{
    "type": "net.app.core.vcard",
    "value": {
        "fn": "Corky Crystal",
        "n": {
            "given-name": "Corky",
            "family-name": "Crystal",
            "additional-name": "",
            "honorific-prefix": "",
            "honorific-suffix": ""
        },
        "nickname": "Corks",
        "org": {
            "organization-name": "Acme Inc.",
            "organization-unit": ""
        },
        "title": "Chief Chef",
        "adr": {
            "type": "WORK",
            "post-office-box": "",
            "street-address": "1 Embarcadero",
            "extended-address": "",
            "locality": "San Francisco",
            "postal-code": "94105",
            "region": "CA",
            "country-name": "United States",
            "value": ""
        },
        "agent": "",
        "bday": "",
        "category": ["cook","baker"],
        "class": "",
        "tel": [{
            "type":"home",
            "value": "+1 415 555 5555"
        }],
        "email": [{
            "type": "",
            "value": "corky@example.com"
        }],
        "geo": {
            "latitude": 74.0064,
            "longitude": 40.7142
        },
        "key": "",
        "label": [""],
        "logo": "",
        "mailer": "",
        "note": "",
        "photo": "",
        "rev": "",
        "role": "",
        "sort-string": "",
        "sound": "",
        "tz": "PDT",
        "uid": "",
        "url": [
            {
                "type": "ADN",
                "value": "http://alpha.app.net/corks"
            },
            {
                "type": "Twitter",
                "value": "http://twitter.com/corks"
            }
        ]
    }
}

[beccadax]

If you really wanted to have a single annotation that included two types of data, it seems like it'd be more natural to compose them than it would be to nest them:

"type": [ "net.app.core.vcard", "net.app.core.geolocation" ],
"data": {
    "fn": "John Appleseed",
    ...
    "latitude": 123.456789,
    ...
}

But why not just use two annotations in that case? I don't see what you gain by combining them.

[swhitley]

@brentdax Yes, I think it's going to be best to just handle it in the documentation. There's an example in the hCard spec where they just document the relationship outside of the code in the instructions.

[swhitley]

I deviated just slightly on the vCard schema above. URL and EMAIL are arrays. The official spec uses single values. I think arrays make more sense for today's data requirements and the first element can be used for compatibility where applications expect a single value.

[orianmarx]

@swhitley I'm closing this issue. If you'd like it to remain active, please open a new issue on https://github.com/appdotnet/object-metadata and include a reference to appdotnet/api-spec#173 to link back to this discussion.