-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathindex.html
1197 lines (1066 loc) · 50.1 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<title>JF2 Post Serialization Format</title>
<meta charset='utf-8'>
<script src='https://www.w3.org/Tools/respec/respec-w3c'
async class='remove'></script>
<script class='remove'>
var respecConfig = {
license: "w3c-software-doc",
specStatus: "ED",
shortName: "jf2",
edDraftURI: "https://jf2.spec.indieweb.org/",
editors: [
{ name: "Kevin Marks",
url: "https://www.kevinmarks.com/",
w3cid: "" },
{ name: "Bebe Roberts",
url: "",
w3cid: "76388" }
],
wg: "Social Web Working Group",
wgURI: "https://www.w3.org/Social/WG",
wgPublicList: "public-socialweb",
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/72531/status",
noRecTrack: true,
otherLinks: [
{
key: "Repository",
data: [
{
value: "GitHub",
href: "https://github.com/indieweb/jf2"
},
{
value: "Issues",
href: "https://github.com/indieweb/jf2/issues"
},
{
value: "Commits",
href: "https://github.com/indieweb/jf2/commits/gh-pages"
}
]
},
{
key: "Test",
data: [
{
value: "Validator",
href: "https://jf2.rocks/"
},
{
value: "Sample Set",
href: "https://jf2.rocks/"
},
{
value: "Implementation Reports",
href: "https://jf2.rocks/"
}
]
}
],
localBiblio: {
"microformats2": {
title: "microformats2",
href: "https://microformats.org/wiki/microformats2",
authors: [ "Tantek Çelik"],
status: "Living Specification",
publisher: "microformats.org"
},
"jsonfeed-v1": {
title: "JSON Feed Version 1",
href: "https://jsonfeed.org/version/1",
authors: [ "Brent Simmons", "Manton Reece"],
status: "Draft",
publisher: "https://jsonfeed.org"
},
}
};
</script>
<link rel="pingback" href="https://webmention.io/w3c/xmlrpc">
<link rel="webmention" href="https://webmention.io/w3c/webmention">
</head>
<body>
<section id='abstract'>
<p>
This document describes a JSON serialization format to describe simple
streams of data as well as single objects of data for data transfer and
processing.
</p>
</section>
<section id='sotd'>
</section>
<section id='authorsnote' class='informative'>
<h2>Author's Note</h2>
<p>
This document is an attempt to unify various simplified versions of the
microformats2 representative JSON format. As such, much of this document
is likely to change as various implementations contribute input.
</p>
</section>
<section class='informative'>
<h2>Introduction</h2>
<p>
JF2 is a JSON based document format that describes single entries of
information and lists of those entries. The primary use case for JF2 is to
create a JSON format for social web post objects to be processed directly by
client software and by other servers.
</p>
<p>
JF2 is vocabulary independent except for its profiles which are fully
vocabulary aware. Rather than defining a new vocabulary the profiles
described in this document use the vocabulary defined by [[microformats2]]
(MF2); however, any other suitable vocabulary could be used. The name JF2
comes from its origins in being a direct parsed format of microformats2 data
from HTML.
</p>
</section>
<section class='informative'>
<h2>Use Cases</h2>
<p>
JF2 has evolved as a result of a variety of use-cases for different implementations
exploring ways to simplify their existing use of canonical parsed microformats2 JSON
output. All of these use cases in particular are simply to have a single format for
the storage and use of social web objects.
</p>
<p>
<a href="https://webmention.io/">Webmention.io</a> is a service that provides Webmention
processing and verification on behalf of other sites. It uses a simple JSON object to
transfer a processed Webmention back to the client site's JavaScript for display. The
attributes are intended to be processed only by the client site's JavaScript code, not
by anything else.
</p>
<p>
<a href="https://github.com/kylewm/mf2util">mf2util</a> is a utility library that provides a layer on top
of microformats processing. The library returns only a simple JSON object and strips
off any unnecessary information leaving the library user only the most essential information.
</p>
<p>
Various services (<a href="https://xray.p3k.io">XRay</a>,
<a href="https://unmung2.appspot.com/">Unmung</a>,
<a href="https://stream.thatmustbe.us/">SocialStreams</a>)
provide conversion from microformats pages into JF2 for quick inspection to
validate proper semantics. These tools have been used in practice to allow for embedded social activity in a page.
</p>
</section>
<section id="conformance">
<section>
<h3>Documents</h3>
<p>
Conforming documents are those that comply with all the conformance
criteria for JF2 documents. For readability, some of these conformance
requirements are phrased as conformance requirements on publishers.
Such requirements are implicitly requirements on documents: by
definition, all documents are assumed to have a publisher.
</p>
<p>
Conforming documents must not use features of JSON-LD or other
serialization features disallowed in this specification. Conforming
documents that include types or properties beyond those defined in
[[microformats2]] must use [[microformats2]]'s prefixing methods to indicate
non-standard properties.
</p>
<p>
A non-exhaustive list of examples of documents includes:
</p>
<ul>
<li>
A document representing an author
</li>
<li>
A document representing an event
</li>
<li>
A document representing a post
</li>
<li>
A document representing a collection of the posts created by an author
</li>
<li>
A document representing a collection of people
</li>
<li>
A document representing a like
</li>
</ul>
</section>
<section>
<h3>Implementations</h3>
<p>
Conforming implementations are software that publish, store, analyze,
consume or otherwise process conforming documents. The two main kinds
of implementations are publishers and consumers.
</p>
<section>
<h4>Publishers</h4>
<p>
Conforming publishers are implementations that create and publish
conforming documents. Conforming publishers must make conforming
documents available according to the serialization requirements of
this document. Conforming publishers must consider privacy as described
in the <a href="#privacy">Privacy</a> section of this document.
Conforming publishers must consider security as described in the
<a href="#security-considerations">Security Considerations</a> section
of this document.
</p>
<p>
A non-exhaustive list of example publishers includes:
</p>
<ul>
<li>
A social network
</li>
<li>
A personal web site
</li>
<li>
A document publishing system
</li>
<li>
A bridge from a non-conforming social network
</li>
<li>
A document converter from similar document types such as RSS, Atom,
or JSON Feed
</li>
</ul>
</section>
<section>
<h4>Consumers</h4>
<p>
Conforming consumers are implementations that read and analyze
conforming documents. Conforming consumers must not halt on any
unrecognized properties or types.
</p>
<p>
Conforming consumers may re-publish conforming documents in other
other data formats. Conforming consumers may present conforming
documents to a user on screen, in print, in audio format, or using
other presentation mechanisms. Conforming consumers must faithfully
translate the information represented in conforming documents into
these other formats or media. Conforming consumers that re-publish
conforming documents must consider privacy and security as described
in the <a href="#privacy">Privacy</a> section and
<a href="#security-considerations">Security Considerations</a> section
of this document.
</p>
<p>A non-exhaustive list of example consumers includes:</p>
<ul>
<li>
A social network
</li>
<li>
A search engine
</li>
<li>
A feed reader
</li>
<li>
A document validator
</li>
<li>
A feed aggregator
</li>
</ul>
</section>
</section>
<section class="informative">
<h3>Validator and Reporting</h3>
<p>
A validator for conforming documents is available at
<a href="https://jf2.rocks/">https://jf2.rocks/</a>.
This also offers example conforming and non-conforming
documents for testing purposes.
</p>
<p>
Please submit your implementation reports at
<a href="https://jf2.rocks/">https://jf2.rocks/</a>.
Instructions are provided at the URL.
</p>
</section>
</section>
<section id='syntax'>
<h2>Syntax</h2>
<p>
JF2 consists of JSON objects which are defined by a <a>type</a> property that will specify
the vocabulary of the object. Properties are attached to these objects which will contain
either a single string, a single object, an array of strings, or an array of objects.
Arrays that have only a single item SHOULD be condensed into only the single containing item.
Any property of an object MAY be a single item or an array of items except for reserved properties
defined below.
</p>
<section id='reservedproperties'>
<h3>Reserved Properties</h3>
<p>
The following properties are reserved and cannot be used as property names in vocabularies.
</p>
<ul>
<li><dfn>type</dfn> defines the object classification. In microformats, this is presumed
to be an h-* class from the microformats2 vocabulary.
Type MUST be a single string value only.</li>
<li><dfn>children</dfn> is a container for all unnamed sub-objects inside
an entry. That is, any sub-object that is not associated to a specific property of the object.
If a children value is set, it MUST be serialized as an array even if only a
single item is present.</li>
<li><dfn>references</dfn> is an associative array, serialized as a JSON object, of all sub-objects
inside an object which have "id" defined as an external [[!URL]].
The authoritative source for all objects in this array is always at the URL, not in this object.
If the references property is defined, it MUST be serialized as an associative array and MUST be
present at the top level entry only.
</li>
<li><dfn>content-type</dfn> is the MIME media type of the containing object's original source.
Content-type MUST be a single string value only.</li>
<li><dfn>html</dfn> is the text/html version of the containing object.
html MUST be a single string value only.</li>
<li><dfn>text</dfn> is the text/plain version of the containing object.
text MUST be a single string value only.</li>
<li><dfn>lang</dfn> is the localization language of the containing object and all
sub-objects, unless overridden by another lang definition.
Setting lang at a lower level overrides any lang value set at higher levels.
This value MUST be a single string value and MUST be a [[!RFC5646]] language tag.</li>
<li><dfn>@context</dfn> is the context of the vocabulary as defined in [[JSON-LD]].
This attribute MAY be omitted and has an inferred value if not present. If it is present it MUST be
present at the top level entry only. See the <a href="#JSON-LD">JSON-LD Consideration</a> section.
</li>
</ul>
</section>
<section id='posts'>
<h3>Posts</h3>
<section id="post-objects">
<h4>Post Objects</h4>
<p>
A post is composed of a "type" property, and one or more additional properties that describe the post.
</p>
<p>
The "type" property has a value that describes the vocabulary of the post. Common values include "entry", "card", etc.
See <a href="https://microformats.org/wiki/microformats-2#v2_vocabularies">microformats2 vocabularies</a>
for the full list when using a microformats based vocabulary.
</p>
<p>
Any additional properties in the post object are considered part of the post's vocabulary.
</p>
</section>
<section id="post-properties">
<h4>Post Properties</h4>
<p>
The list of valid post properties is defined by the vocabularies. This allows new vocabularies to be developed outside the development of the syntax.
</p>
<p>
Most values will be strings. If a property (such as "author" for example) references another
object, it may be serialized in two ways: as an inline JSON object or as the unique identifier
or [[!URL]] where the object can be found. See <a href="#using-references">Using References</a>.
</p>
<p>
Values MAY also be arrays if the vocabulary allows for multiple values of the property.
</p>
</section>
<section id="example-post">
<h4>Example Post</h4>
<pre class="example">
{
"type": "entry",
"published": "2015-10-20T15:49:00-0700",
"url": "https://example.com/post/fsjeuu8372",
"author": {
"type": "card",
"name": "Alice",
"url": "https://alice.example.com",
"photo": "https://alice.example.com/photo.jpg"
},
"name": "Hello World",
"content": "This is a blog post",
"category": "Posts"
}
</pre>
<pre class="example">
{
"type": "entry",
"published": "2015-10-20T15:49:00-0700",
"url": "https://example.com/like/r23eugi02c",
"author": {
"type": "card",
"name": "Alice",
"url": "https://alice.example.com",
"photo": "https://alice.example.com/photo.jpg"
},
"like-of": "https://bob.example.com/post/100",
"category": ["Likes", "Posts"]
}
</pre>
</section>
</section>
<section id="author">
<h3>Author</h3>
<p>
An author is represented by the [[!h-card]] vocabulary, and consists of a name, photo [[!URL]], [[!URL]] to the author profile,
and <a href="https://microformats.org/wiki/h-card">others</a>. This is represented by the following JSON.
</p>
<pre class="example">
{
"type": "card",
"name": "Aaron Parecki",
"photo": "https://aaronparecki.com/photo.jpg",
"url": "https://aaronparecki.com/"
}
</pre>
</section>
<section id="html-content">
<h3>HTML Content</h3>
<p>
By default, any string value should be interpreted as literal plaintext.
This means when displaying a string in an HTML page, it must be HTML escaped.
</p>
<p>
If the value of a property is to be interpreted as HTML, it MUST be enclosed in
an object and placed under the "html" property as follows. If a plaintext version
is also available, that is placed under the "text" property.
</p>
<pre class="example">
{
"type": "entry",
"content": {
"html": "<p>Hello World</p>",
"text": "Hello World"
}
}
</pre>
<section id="multiple-urls">
<h4>Multiple URLs for video/audio/picture</h4>
<p>
Since HTML video/audio/picture tags may have multiple URLs, we need a way to convey this information in the JSON representation.
In such situations, vocabulary properties MAY be arrays.
</p>
<p>
For example, this HTML (marked up with microformats2):
</p>
<pre class="example">
<div class="h-entry">
<video class="u-video" width="640" height="360" preload controls>
<source src="sample_h264.mov" type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"' />
<source src="sample_ogg.ogv" type='video/ogg; codecs="theora, vorbis"' />
<source src="sample_webm.webm" type='video/webm; codecs="vp8, vorbis"' />
</video>
</div>
</pre>
<p>
could be represented with this JSON:
</p>
<pre class="example">
{
"type": "entry",
"video": [
{
"content-type": "video/mp4",
"url": "sample_h264.mov"
},
{
"content-type": "video/ogg",
"url": "sample_ogg.ogg"
},
{
"content-type": "video/webm",
"url": "sample_webm.webm"
}
]
}
</pre>
</section>
</section>
</section>
<section id="using-references">
<h2>Using References</h2>
<p>
The purpose of the <a>references</a> property is to exclude any non-authoritative
data from the defined object. To do this, non-authoritative data is moved so
that implementations looking to process only authoritative data may simply ignore
the references property and fetch any data that would be contained there from its
authoritative source.
</p>
<p>
If a property is a reference to an object that is defined authoritatively in
some other location, the <a>references</a> property SHOULD be used. The property
SHOULD contain only the unique identifier or [[!URL]] where the authoritative data
may be found. In the references object, the URL or unique identifier MAY
be used as the property key and a serialization of the referenced object MAY
be provided as the property value. This serialization of the referenced object MAY
be incomplete so as to provide only necessary data.
</p>
<p>
Parsing implementations SHOULD fetch data from the authoritative source instead of using
the references object.
</p>
<section id="">
<h3>Example of References</h3>
<pre class="example">
{
"type": "entry",
"published": "2015-10-20T15:49:00-0700",
"url": "https://example.com/post/fsjeuu8372",
"author": "https://alice.example.com",
"name": "Hello World",
"content": "This is a blog post",
"category": "Posts",
"references": {
"https://alice.example.com": {
"type": "card",
"name": "Alice",
"url": "https://alice.example.com",
"photo": "https://alice.example.com/photo.jpg"
}
}
}
</pre>
<pre class="example">
{
"type": "entry",
"published": "2015-10-20T15:49:00-0700",
"url": "https://example.com/like/r23eugi02c",
"author": {
"type": "card",
"name": "Alice",
"url": "https://alice.example.com",
"photo": "https://alice.example.com/photo.jpg"
},
"like-of": "https://bob.example.com/post/100",
"category": ["Likes", "Posts"],
"references": {
"https://bob.example.com/post/100": {
"type": "entry",
"published": "2015-10-18T12:33:00-0700",
"url": "https://bob.example.com/post/100",
"author": "https://bob.example.com",
"name": "My First Post",
"content": "This is my first post on my new blog, I hope you like it"
},
"https://bob.example.com": {
"type": "card",
"name": "Bob",
"url": "https://bob.example.com",
"photo": "https://bob.example.com/mypicture.jpg"
}
}
}
</pre>
</section>
</section>
<section id="collections">
<h2>Collections</h2>
<p>
Posts can be contained inside of collections. A collection may be a home page feed, or a feed of other posts such as a list of contacts, a list of things someone has liked, etc. There is no requirement that all posts in a collection need to be of the same type.
</p>
<p>
The collection may also have its own properties such as "name" or "author".
</p>
<pre class="example">
{
"type": "feed",
"url": "https://alice.example.com/collectionurl",
"name": "Alice's Home Page",
"author": {
"type": "card",
"name": "Alice",
"url": "https://alice.example.com",
"photo": "https://alice.example.com/photo"
},
"children": [
{
"type": "entry",
"content": {
"html": "<p>Hello World</p>",
"text": "Hello World"
}
},
{
"type": "entry",
"content": {
"html": "<p>A Second Post</p>",
"text": "A Second Post"
}
}
]
}
</pre>
<section id="multiple-items">
<h3>Multiple items on a page</h3>
<p>
If an HTML page contains multiple top-level items, (most commonly found when a page contains a list of [[h-entry]] objects), the parser creates an implicit top-level collection with no properties.
</p>
<pre class="example">
{
"children": [
{
"type": "entry",
"content": {
"html": "<p>Hello World</p>",
"text": "Hello World"
}
},
{
"type": "entry",
"content": {
"html": "<p>A Second Post</p>",
"text": "A Second Post"
}
}
]
}
</pre>
</section>
</section>
<section id="deriving">
<h2>Deriving the Syntax</h2>
<p>
This syntax is derived from HTML with microformats2 converted to JSON with [[!microformats2-parsing]], then converted to a simplified JSON. The examples below illustrate the process.
</p>
<section id="deriving-note">
<h3>Deriving a Note</h3>
<h4>HTML + Microformats</h4>
<pre class="example">
<article class="h-entry">
<h1 class="p-name">Hello World</h1>
<p>Published by <a class="p-author h-card" href="https://example.com/">A. Developer</a>
on <a href="https://example.com/2015/10/21" class="u-url"><time class="dt-published" datetime="2015-10-21T12:00:00-0700">October 21<sup>st</sup>, 2015</time></a>
<p class="p-summary">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus imperdiet ultrices pulvinar.</p>
<div class="e-content"><p>Donec dapibus enim lacus, <i>a vehicula magna bibendum non</i>. Phasellus id lacinia felis, vitae pellentesque enim. Sed at quam dui. Suspendisse accumsan, est id pulvinar consequat, urna ex tincidunt enim, nec sodales lectus nulla et augue. Cras venenatis vehicula molestie. Donec sagittis elit orci, sit amet egestas ex pharetra in.</p></div>
</article>
</pre>
<h4>Parsed Microformats JSON</h4>
<pre class="example">
{
"items": [
{
"type": [
"h-entry"
],
"properties": {
"author": [
{
"type": [
"h-card"
],
"properties": {
"name": [
"A. Developer"
],
"url": [
"https://example.com/"
]
},
"value": "A. Developer"
}
],
"name": [
"Hello World"
],
"summary": [
"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus imperdiet ultrices pulvinar."
],
"url": [
"https://example.com/2015/10/21"
],
"published": [
"2015-10-21T12:00:00-0700"
],
"content": [
{
"html": "<p>Donec dapibus enim lacus, <i>a vehicula magna bibendum non</i>. Phasellus id lacinia felis, vitae pellentesque enim. Sed at quam dui. Suspendisse accumsan, est id pulvinar consequat, urna ex tincidunt enim, nec sodales lectus nulla et augue. Cras venenatis vehicula molestie. Donec sagittis elit orci, sit amet egestas ex pharetra in.</p>",
"value": "Donec dapibus enim lacus, a vehicula magna bibendum non. Phasellus id lacinia felis, vitae pellentesque enim. Sed at quam dui. Suspendisse accumsan, est id pulvinar consequat, urna ex tincidunt enim, nec sodales lectus nulla et augue. Cras venenatis vehicula molestie. Donec sagittis elit orci, sit amet egestas ex pharetra in."
}
]
}
}
]
}
</pre>
<h4>Simplified JSON</h4>
<pre class="example">
{
"type": "entry",
"author": {
"type": "card",
"url": "https://example.com",
"name": "A. Developer"
},
"url": "https://example.com/2015/10/21",
"published": "2015-10-21T12:00:00-0700",
"name": "Hello World",
"summary": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus imperdiet ultrices pulvinar.",
"content": {
"html": "<p>Donec dapibus enim lacus, <i>a vehicula magna bibendum non</i>. Phasellus id lacinia felis, vitae pellentesque enim. Sed at quam dui. Suspendisse accumsan, est id pulvinar consequat, urna ex tincidunt enim, nec sodales lectus nulla et augue. Cras venenatis vehicula molestie. Donec sagittis elit orci, sit amet egestas ex pharetra in.</p>",
"text": "Donec dapibus enim lacus, a vehicula magna bibendum non. Phasellus id lacinia felis, vitae pellentesque enim. Sed at quam dui. Suspendisse accumsan, est id pulvinar consequat, urna ex tincidunt enim, nec sodales lectus nulla et augue. Cras venenatis vehicula molestie. Donec sagittis elit orci, sit amet egestas ex pharetra in."
}
}
</pre>
</section>
<section id="JSON-LD">
<h2>JSON-LD Consideration</h2>
<p>
JF2 documents all have an implicit @context field which is optional. This @context can be found at
<a href="https://www.w3.org/ns/jf2">https://www.w3.org/ns/jf2</a>
and is provided only to make conversion to [[JSON-LD]] format possible. Most JF2 will process
fine in JSON-LD systems, however, this support is not guaranteed and those wishing to
use JF2 in JSON-LD may need to modify serialization slightly.
</p>
</section>
</section>
<section id="profiles">
<h2>Profiles</h2>
<section id="profile_introduction" class="informative">
<h3>Intro</h3>
<p>
JF2 on its own is intentionally vocabulary independent, that is, any value may contain a single value, a
set of values, or a structure and there are no requirements that fields be present. While this keeps
the fidelity of the original [[microformats2]] encoded HTML, some consuming code can be simplified by
adding vocabulary requirements. This creates the need for vocabulary aware profiles of JF2, where
the profile adds additional constraints on the fields present.
</p>
</section>
<section id="jf2feed">
<h3>JF2 Feed</h3>
<section id="jf2feed_intro" class="informative">
<h4>Introduction</h4>
<p>
XML formats have heavily dominated serializations of social activity feeds for blogs and news feeds for years.
Several attempts have been created over the years to attempt to bring these to a JSON format, most recently
[[jsonfeed-v1]], which JF2 Feed gets the majority of its requirements from. JF2 Feed is an attempt to bring
some of the advantages of these vocabulary aware specifications under a standard vocabulary from
[[microformats2]].
</p>
<p>
Fields described below have additional requirements to be considered a valid JF2 Feed, however they may contain
any number of additional fields from [[h-feed]], [[h-entry]], and [[h-card]]. The fields below are codified as
they are likely the most useful for feed readers; additional data is expected to be fetchable at the entry URL,
preferably though valid [[microformats2]] markup.
</p>
</section>
<section id="jf2feed_required_fields">
<h4>Required Fields and Required Formats</h4>
<p>
The following fields have additional constraints to be a valid JF2 Feed that only apply
to the top level feed object, its child entry object, and any properties of them.
</p>
<ul>
<li><strong>type</strong> MUST be defined with a value of "feed" on the top level entry.
All other sub-object items MUST NOT have a type value of "feed". All direct children
of the top level feed object MUST have a value of "entry".
</li>
<li><strong>name</strong> MUST be defined on the top level "feed" object. This value MUST
be a single string value. Any direct children of the top level item SHOULD have this
property and if present MUST be a single string value.
</li>
<li><strong>url</strong> SHOULD be defined on the top level "feed" object. This value MUST
be a single string value and is expected to contain the [[!URL]] of the data which this
JF2 Feed describes. Additionally, if present in the author property object, or any direct
child entry object, it MUST contain a single string value only and that value must be a [[!URL]].
</li>
<li><strong>photo</strong> MUST be a single string value if present on the top level feed
object, its author property object, or any direct child entry object and MUST be a valid [[!URL]].
</li>
<li><strong>uid</strong> MUST be present on any entry object which is a direct child of the
top level feed object. This property MUST be a single string value and MUST uniquely
identify this entry object. This MAY be a duplicate of the entry's url property.
</li>
<li><strong>published</strong> SHOULD be present on any entry object which is a direct
child of the top level feed object. If present, this property MUST be a single string
value and MUST be formatted as specified by [[!ISO8601]].
</li>
<li><strong>updated</strong> MAY be present on any entry object which is a direct
child of the top level feed object. If present, this property MUST be a single string
value and MUST be formatted as specified by [[!ISO8601]].
</li>
<li><strong>category</strong> MAY be present on any entry object which is a direct
child of the top level feed object. If present, this property MUST be an array of
string values.
</li>
<li><strong>author</strong> MAY be present on the top level feed or second level entry
objects. If present, it MUST be an object and it MUST contain at least a name, url,
or photo property.
</li>
<li><strong>content</strong> MAY be present on any entry object which is a direct
child of the top level feed object. If present, this property MUST be an object as
described in the <a href="#html-content">HTML content</a> regardless if only a text/plain
version is available.
</li>
<li><strong>summary</strong> MAY be present on any second level entry object. If present,
it MUST be a single string.
</li>
<li><strong>video or audio</strong> MAY be present on any second level entry object. If present,
it MUST be an object as described in the <a href="#multiple-urls">multiple URLs</a> section with
at least a 'url' property which MUST be a single string and a valid [[!URL]].
</li>
</ul>
<p class="note">
The format of published and updated fields may change from [[ISO8601]] to [[RFC3339]] or use [[microformats2]]'s more liberal date field. Please discuss on github issues
</p>
</section>
<section id="jf2feed_discovery">
<h4>Discovery</h4>
<p>
The JF2 Feed for a page may be published as HTTP Link header [[!RFC5988]], or as an HTML
<link> or <a> tag element with the following attributes.
<pre>rel="alternate" type="application/jf2feed+json" href="https://example.com/jf2feed.json" </pre>
</p>
</section>
<section id="jf2feed_example">
<h4>JF2 Feed Example</h4>
<pre class="example">
{
"type": "feed",
"url": "https://example.org/myfeed.html",
"name": "Brent Simmons’s Microblog",
"author": {
"type": "card",
"name": "Brent Simmons",
"url": "https://example.org/",
"photo": "https://example.org/avatar.png"
},
"children": [
{
"type": "entry",
"uid": "https://example.org/2347259",
"url": "https://example.org/2347259",
"content": {
"text": "Cats are neat. \n\nhttps://example.org/cats"
},
"published": "2016-02-09T14:22:00-07:00"
}
]
}
</pre>
</section>
<section id="jsonfeed_to_jf2feed" class="informative">
<h4>JSON Feed to JF2 conversion</h4>
<p class="note">
As it is not sane to do this for every feed serialization currently available,
this section is likely to only be temporary in the spec and may be moved to a
more permanant home elsewhere.
</p>
<p>
JF2 Feed was based heavily on [[jsonfeed-v1]] and as such it is quite trivial to process a
JSON Feed as a JF2 Feed with only minor changes. This section discusses the conversion that
must be made for this process, most of which is simply conversion of properties to their
[[microformats2]] equivalent.
</p>
<p>
<strong>Conversion of the top level structure</strong>
</p>
<ul>
<li>Drop or ignore the "version" property</li>
<li>Create a property "type" with the value "feed"</li>
<li>Rename the properties "title" to "name", "home_page_url" to "url", "icon" to "photo", and "description" to "summary"</li>
<li>Modify the "author" property as described below</li>
<li>Rename the "items" property to "children" and modify as described below</li>
</ul>
<p>
<strong>Conversion of the author property on the top level or on any lower level entry</strong>
</p>
<ul>
<li>Rename the property 'avatar' to 'photo'</li>
</ul>
<p>
<strong>Conversion of each entry in items</strong>
</p>
<ul>
<li>Rename the 'id' property to 'uid'</li>
<li>Convert content_html and content_text into a single object under the property "content" with properties "html" and "text", leaving out either if not present or the entire property if neither are present</li>
<li>Rename the properties
"title" to "name",
"image" to "photo",
"date_published" to "published",
"date_modified" to "updated",
"tags" to "category",
"banner_image" to "featured" </li>
<li>Drop or ignore the 'external_url' property. If content is not set, it may be useful to set content['text'] to the value of 'external_url'</li>
<li>Keep "summary" property the same</li>
<li>
For each entry in the "attachments" array,
<ol>
<li>Rename "mime-type" to "content-type".</li>
<li>Keep the "url" property as is.</li>
<li>If the "content-type" field begins with "video/", add the item to the "video" property array.</li>
<li>If the "content-type" field begins with "image/", add the item to the "photo" property array.</li>
</ol>
</li>
</ul>
<p>
It may be benefitial to drop any properties other than those mentioned to avoid conflicts with any future [[microformats2]] properties.
</p>
</section>
</section>
</section>
<section id="extensions">
<h2>Extension</h2>
<p>
JF2 MAY be extended by the [[!microformats2]] extension mechanism. The 'x-*' properties created in this
way MAY be present in any serialization of JF2. Parsers MUST NOT halt on any unknown properties they
encounter.
</p>
</section>
<section id="internationalization" class="informative">
<h2>Language And Internationalization</h2>
<p>
In order to allow any language to be serialized in JF2, the 'lang' value can be set on any object to annotate
the natural language of the text. Many often ask for control structures like directionality of text and