···
(** The type representing a complete JSON Feed. *)
13
-
(** {1 Jsont Type} *)
16
-
(** Declarative JSON type for JSON feeds.
14
+
(** Declarative type that describes the structure of JSON Feeds.
Maps the complete JSON Feed 1.1 specification including all required and
type t = (string * Jsont.json) list
23
-
(** Unknown/unrecognized JSON object members. Useful for preserving fields
21
+
(** Unknown or unrecognized JSON object members. Useful for preserving fields
from custom extensions or future spec versions. *)
···
(** [is_empty u] returns [true] if there are no unknown fields. *)
31
+
(** {1 Construction} *)
···
50
+
(** [create ~title ~items ()] creates a new JSON Feed.
53
+
The name of the feed. Required field that should be plain text, not HTML.
54
+
@param home_page_url
55
+
The URL of the resource that the feed describes. This resource may or may
56
+
not actually be a "home" page, but it should be an HTML page. If a feed is
57
+
for a podcast, for instance, the home_page_url would be the URL for the
60
+
The URL of the feed itself. This is the URL that was requested to get this
61
+
JSON Feed response. Helps feed readers to determine when they're being
62
+
redirected. Strongly recommended for feeds.
64
+
A plain text description of the feed, for human consumption. May contain
65
+
some formatting (like newlines).
67
+
A description of the purpose of the feed, for a person looking at the raw
68
+
JSON. This is for the publisher's use only, not intended to be displayed
71
+
The URL of a feed that provides the next n items, where n is determined by
72
+
the publisher. Used for pagination. A feed reader may continue to request
73
+
the URLs in next_url until it reaches a feed without a next_url.
75
+
The URL of an image for the feed suitable to be used in a timeline, much
76
+
the way an avatar might be used. Should be square and relatively large -
77
+
such as 512 x 512 pixels - and may be cropped to a circle or rounded
78
+
corners. Should not be transparent.
80
+
The URL of an image for the feed suitable to be used in a source list.
81
+
Should be square and relatively small - such as 64 x 64 pixels. Should not
84
+
Specifies one or more feed authors. The author object has several members
85
+
(name, url, avatar) which are all optional, but at least one must be
86
+
present for the object to be valid.
88
+
The primary language for the feed in RFC 5646 format. The value can be a
89
+
language tag such as "en" or "en-US", or a language-region combination.
91
+
Whether or not the feed is finished - that is, whether or not it will ever
92
+
update again. A feed for a temporary event, like an instance of a
93
+
conference, may expire. If the value is [true], feed readers may stop
94
+
checking for updates.
96
+
Endpoints that can be used to subscribe to real-time notifications from
97
+
the publisher of this feed. Each hub object has a type (such as "rssCloud"
98
+
or "WebSub") and url.
100
+
The items in the feed. Required field, though it may be an empty array.
102
+
Unknown JSON object members preserved from parsing. Useful for custom
105
+
(** {1 Accessors} *)
val version : t -> string
108
+
(** [version feed] returns the URL of the version of the format the feed uses.
109
+
This will always be "https://jsonfeed.org/version/1.1" for feeds created
110
+
with this library. This is a required field in the JSON Feed spec. *)
113
+
(** [title feed] returns the name of the feed. This is plain text and should not
114
+
contain HTML. This is a required field. *)
val home_page_url : t -> string option
117
+
(** [home_page_url feed] returns the URL of the resource that the feed
118
+
describes. This resource may or may not actually be a "home" page, but it
119
+
should be an HTML page. For instance, if a feed is for a podcast, the
120
+
home_page_url would be the URL for the podcast's website. *)
val feed_url : t -> string option
123
+
(** [feed_url feed] returns the URL of the feed itself. This should be the URL
124
+
that was requested to get this JSON Feed response. It helps feed readers
125
+
determine when they're being redirected. This is strongly recommended for
val description : t -> string option
129
+
(** [description feed] returns a plain text description of the feed, for human
130
+
consumption. This field may contain some formatting such as newlines. *)
val user_comment : t -> string option
133
+
(** [user_comment feed] returns a description of the purpose of the feed, for a
134
+
person looking at the raw JSON. This is for the publisher's use only and is
135
+
not intended to be displayed to end users. *)
val next_url : t -> string option
138
+
(** [next_url feed] returns the URL of a feed that provides the next n items,
139
+
where n is determined by the publisher. This is used for pagination. A feed
140
+
reader may continue to request the URLs in next_url until it reaches a feed
141
+
without a next_url. *)
val icon : t -> string option
144
+
(** [icon feed] returns the URL of an image for the feed suitable to be used in
145
+
a timeline, much the way an avatar might be used. It should be square and
146
+
relatively large (such as 512 x 512 pixels) and may be cropped to a circle
147
+
or rounded corners by feed readers. It should not be transparent. *)
val favicon : t -> string option
150
+
(** [favicon feed] returns the URL of an image for the feed suitable to be used
151
+
in a source list. It should be square and relatively small (such as 64 x 64
152
+
pixels) and should not be transparent. *)
val authors : t -> Author.t list option
155
+
(** [authors feed] returns the feed authors. Each author object has several
156
+
members (name, url, avatar) which are all optional, but at least one must be
157
+
present for the object to be valid. If a feed has multiple authors, they
158
+
should all be listed here. *)
val language : t -> string option
161
+
(** [language feed] returns the primary language for the feed in RFC 5646
162
+
format. The value can be a language tag such as "en" or "en-US", or a
163
+
language-region combination. This field helps feed readers present the feed
164
+
in the appropriate language. *)
val expired : t -> bool option
167
+
(** [expired feed] returns whether the feed is finished - that is, whether it
168
+
will ever update again. A feed for a temporary event, like an instance of a
169
+
conference, may expire. If the value is [Some true], feed readers may stop
170
+
checking for updates. *)
val hubs : t -> Hub.t list option
173
+
(** [hubs feed] returns endpoints that can be used to subscribe to real-time
174
+
notifications from the publisher of this feed. Each hub object has a type
175
+
(such as "rssCloud" or "WebSub") and a url. Feed readers can use these to
176
+
get immediate updates when new items are published. *)
val items : t -> Item.t list
179
+
(** [items feed] returns the array of items in the feed. This is a required
180
+
field, though it may be an empty list. Items represent the individual
181
+
entries in the feed - blog posts, podcast episodes, microblog posts, etc. *)
val unknown : t -> Unknown.t
184
+
(** [unknown feed] returns any unknown JSON object members that were preserved
185
+
during parsing. This is useful for custom extensions or fields from future
186
+
versions of the spec. *)
(** {1 Encoding and Decoding} *)
anil.recoil.org